<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.5">
<meta name="author" content="2019-08-08 13:15:33 CEST">
<title>N4JS Language Specification</title>
<link rel="stylesheet" href="styles/spec.min.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.6.3/css/font-awesome.min.css">
<!-- ************* docinfo ******************************************************************* -->


<!-- ************* Favicon ************-->
<link rel="icon" href="images/favicon.ico" />

<!-- ************* Back-to-top JQuery ************* -->
<script src="https://code.jquery.com/jquery-1.12.4.js"></script>
<script src="https://code.jquery.com/ui/1.12.0/jquery-ui.js"></script>


<link href="styles/prism.min.css" rel="stylesheet" />
<script type="text/javascript" async
  src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.2/MathJax.js?config=TeX-MML-AM_CHTML">
</script>

<!-- ************* Styles ************* -->
<link rel="stylesheet" type="text/css" href="styles/n4jsspec-adoc.css">


<!-- ****************** NavBar ****************** -->
<div id="menubar">
	<div class="banner">
        <a href="https://www.eclipse.org/n4js/#"><img id="logo" src="images/n4js-logo.png" alt="Eclipse N4JS"></a>
    </div>
<ul>
  <li><a href="index.html">Index</a></li>
</ul>
</div>
<!-- ************* docinfo ******************************************************************* -->
<style>
      .admonitionblock td.icon .icon-todo:before{content:"\f249";color:#f4ee42}
    </style>
</head>
<body class="book toc2 toc-left">
<div id="header">
<h1>N4JS Language Specification</h1>
<div class="details">
<span id="author" class="author">2019-08-08 13:15:33 CEST</span><br>
<span id="revnumber">version 0.9</span>
</div>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="introduction.html#_introduction">1. Introduction</a>
<ul class="sectlevel2">
<li><a href="introduction.html#_notation">1.1. Notation</a>
<ul class="sectlevel3">
<li><a href="introduction.html#_grammar-notation">1.1.1. Grammar Notation</a></li>
<li><a href="introduction.html#_type-judgments-and-rules-and-constraints-notation">1.1.2. Type Judgments and Rules and Constraints Notation</a>
<ul class="sectlevel4">
<li><a href="introduction.html#_typing-rules-and-judgments">1.1.2.1. Typing Rules and Judgments</a></li>
<li><a href="introduction.html#_types-of-an-element">1.1.2.2. Types of an Element</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="introduction.html#_auxiliary-functions">1.2. Auxiliary Functions</a>
<ul class="sectlevel3">
<li><a href="introduction.html#_binding">1.2.1. Binding</a></li>
<li><a href="introduction.html#_merging-types">1.2.2. Merging Types</a>
<ul class="sectlevel4">
<li><a href="introduction.html#_logic-formulas">1.2.2.1. Logic Formulas</a></li>
</ul>
</li>
<li><a href="introduction.html#_symbols-and-font-convention">1.2.3. Symbols and Font Convention</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="grammar.html#_grammar">2. Grammar</a>
<ul class="sectlevel2">
<li><a href="grammar.html#_lexical-conventions">2.1. Lexical Conventions</a>
<ul class="sectlevel3">
<li><a href="grammar.html#_identifier-names-and-identifiers">2.1.1. Identifier Names and Identifiers</a></li>
<li><a href="grammar.html#_this-keyword">2.1.2. This Keyword</a></li>
<li><a href="grammar.html#_regular-expression-literals">2.1.3. Regular Expression Literals</a></li>
<li><a href="grammar.html#_automatic-semicolon-insertion">2.1.4. Automatic Semicolon Insertion</a></li>
<li><a href="grammar.html#_jsdoc">2.1.5. JSDoc</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="names.html#_names">3. Names</a>
<ul class="sectlevel2">
<li><a href="names.html#_access-control">3.1. Access Control</a></li>
<li><a href="names.html#_accessibility-of-types-top-level-variables-and-function-declarations">3.2. Accessibility of Types, Top-Level Variables and Function Declarations</a>
<ul class="sectlevel3">
<li><a href="names.html#_accessibility-of-members">3.2.1. Accessibility of Members</a></li>
<li><a href="names.html#_valid-names">3.2.2. Valid Names</a></li>
<li><a href="names.html#_qualified-names">3.2.3. Qualified Names</a></li>
<li><a href="names.html#_name-duplicates">3.2.4. Name Duplicates</a>
<ul class="sectlevel4">
<li><a href="names.html#_lexical-environment">3.2.4.1. Lexical Environment</a></li>
<li><a href="names.html#_duplicates-and-shadowing">3.2.4.2. Duplicates and Shadowing</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="types.html#_types">4. Types</a>
<ul class="sectlevel2">
<li><a href="types.html#_overview">4.1. Overview</a></li>
<li><a href="types.html#_type-expressions">4.2. Type Expressions</a>
<ul class="sectlevel3">
<li><a href="types.html#_syntax">4.2.1. Syntax</a></li>
<li><a href="types.html#_properties">4.2.2. Properties</a></li>
<li><a href="types.html#_semantics">4.2.3. Semantics</a></li>
</ul>
</li>
<li><a href="types.html#_type-inference">4.3. Type Inference</a></li>
<li><a href="types.html#_generic-and-parameterized-types">4.4. Generic and Parameterized Types</a>
<ul class="sectlevel3">
<li><a href="types.html#_generic-types">4.4.1. Generic Types</a></li>
<li><a href="types.html#_type-variables">4.4.2. Type Variables</a></li>
<li><a href="types.html#_parameterized-types">4.4.3. Parameterized Types</a></li>
</ul>
</li>
<li><a href="types.html#_primitive-ecmascript-types">4.5. Primitive ECMAScript Types</a>
<ul class="sectlevel3">
<li><a href="types.html#_undefined-type">4.5.1. Undefined Type</a></li>
<li><a href="types.html#_null-type">4.5.2. Null Type</a></li>
<li><a href="types.html#_primitive-boolean-type">4.5.3. Primitive Boolean Type</a></li>
<li><a href="types.html#_primitive-string-type">4.5.4. Primitive String Type</a></li>
<li><a href="types.html#_primitive-number-type">4.5.5. Primitive Number Type</a></li>
<li><a href="types.html#_primitive-type-int">4.5.6. Primitive Type int</a></li>
<li><a href="types.html#_primitive-symbol-type">4.5.7. Primitive Symbol Type</a></li>
</ul>
</li>
<li><a href="types.html#_primitive-n4js-types">4.6. Primitive N4JS Types</a>
<ul class="sectlevel3">
<li><a href="types.html#_any-type">4.6.1. Any Type</a>
<ul class="sectlevel4">
<li><a href="types.html#any-type-semantics">4.6.1.1. Semantics</a></li>
<li><a href="types.html#any-type-type-inference">4.6.1.2. Type Inference</a>
<ul class="sectlevel5">
<li><a href="types.html#_default-type-of-variables">4.6.1.2.1. Default Type of Variables</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="types.html#_void-type">4.6.2. Void Type</a>
<ul class="sectlevel4">
<li><a href="types.html#void-type-semantics">4.6.2.1. Semantics</a></li>
</ul>
</li>
<li><a href="types.html#_unknown-type">4.6.3. Unknown Type</a></li>
<li><a href="types.html#_primitive-pathselector-and-i18nkey">4.6.4. Primitive Pathselector and I18nKey</a>
<ul class="sectlevel4">
<li><a href="types.html#pathselector-semantics">4.6.4.1. Semantics</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="types.html#_built-in-ecmascript-object-types">4.7. Built-in ECMAScript Object Types</a>
<ul class="sectlevel3">
<li><a href="types.html#ECMAScript-objects-semantics">4.7.1. Semantics</a></li>
<li><a href="types.html#_object-type">4.7.2. Object Type</a></li>
<li><a href="types.html#_function-object-type">4.7.3. Function-Object-Type</a></li>
<li><a href="types.html#_array-object-type">4.7.4. Array Object Type</a></li>
<li><a href="types.html#_string-object-type">4.7.5. String Object Type</a></li>
<li><a href="types.html#_boolean-object-type">4.7.6. Boolean Object Type</a></li>
<li><a href="types.html#_number-object-type">4.7.7. Number Object Type</a></li>
<li><a href="types.html#_global-object-type">4.7.8. Global Object Type</a></li>
<li><a href="types.html#_symbol">4.7.9. Symbol</a></li>
<li><a href="types.html#_promise">4.7.10. Promise</a></li>
<li><a href="types.html#_iterator-interface">4.7.11. Iterator Interface</a></li>
<li><a href="types.html#_iterable-interface">4.7.12. Iterable Interface</a></li>
</ul>
</li>
<li><a href="types.html#_built-in-n4js-types">4.8. Built-In N4JS Types</a>
<ul class="sectlevel3">
<li><a href="types.html#_n4object">4.8.1. N4Object</a>
<ul class="sectlevel4">
<li><a href="types.html#N4Object-semantics">4.8.1.1. Semantics</a></li>
</ul>
</li>
<li><a href="types.html#_n4class">4.8.2. N4Class</a></li>
<li><a href="types.html#IterableN">4.8.3. IterableN</a></li>
</ul>
</li>
<li><a href="types.html#_type-modifiers">4.9. Type Modifiers</a>
<ul class="sectlevel3">
<li><a href="types.html#Type_Modifiers_Dynamic">4.9.1. Dynamic</a></li>
<li><a href="types.html#_optional-return-types">4.9.2. Optional Return Types</a></li>
</ul>
</li>
<li><a href="types.html#_union-and-intersection-type-composed-types">4.10. Union and Intersection Type (Composed Types)</a>
<ul class="sectlevel3">
<li><a href="types.html#_union-type">4.10.1. Union Type</a>
<ul class="sectlevel4">
<li><a href="types.html#union-type-syntax">4.10.1.1. Syntax</a></li>
<li><a href="types.html#union-type-semantics">4.10.1.2. Semantics</a></li>
<li><a href="types.html#_warnings">4.10.1.3. Warnings</a></li>
</ul>
</li>
<li><a href="types.html#_intersection-type">4.10.2. Intersection Type</a>
<ul class="sectlevel4">
<li><a href="types.html#intersection-type-syntax">4.10.2.1. Syntax</a></li>
<li><a href="types.html#intersection-type-semantics">4.10.2.2. Semantics</a></li>
<li><a href="types.html#_warnings-2">4.10.2.3. Warnings</a></li>
</ul>
</li>
<li><a href="types.html#_composed-types-in-wildcards">4.10.3. Composed Types in Wildcards</a></li>
<li><a href="types.html#_property-access-for-composed-types">4.10.4. Property Access for Composed Types</a>
<ul class="sectlevel4">
<li><a href="types.html#_properties-of-union-type">4.10.4.1. Properties of Union Type</a>
<ul class="sectlevel5">
<li><a href="types.html#_remarks-on-union-type-s-members">4.10.4.1.1. Remarks on union type’s members:</a></li>
</ul>
</li>
<li><a href="types.html#_properties-of-intersection-type">4.10.4.2. Properties of Intersection Type</a>
<ul class="sectlevel5">
<li><a href="types.html#_remarks-on-intersection-type-s-methods">4.10.4.2.1. Remarks on intersection type’s methods:</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="types.html#_constructor-and-classifier-type">4.11. Constructor and Classifier Type</a>
<ul class="sectlevel3">
<li><a href="types.html#_syntax-3">4.11.1. Syntax</a></li>
<li><a href="types.html#_semantics-2">4.11.2. Semantics</a></li>
<li><a href="types.html#_constructors-and-prototypes-in-ecmascript-2015">4.11.3. Constructors and Prototypes in ECMAScript 2015</a></li>
</ul>
</li>
<li><a href="types.html#_this-type">4.12. This Type</a>
<ul class="sectlevel3">
<li><a href="types.html#this-type-syntax">4.12.1. Syntax</a></li>
<li><a href="types.html#this-keyword-semantics">4.12.2. Semantics</a></li>
</ul>
</li>
<li><a href="types.html#_enums">4.13. Enums</a>
<ul class="sectlevel3">
<li><a href="types.html#_enums-n4js">4.13.1. Enums (N4JS)</a>
<ul class="sectlevel4">
<li><a href="types.html#enums-syntax">4.13.1.1. Syntax</a></li>
<li><a href="types.html#enums-semantics">4.13.1.2. Semantics</a></li>
</ul>
</li>
<li><a href="types.html#_string-based-enums">4.13.2. String-Based Enums</a></li>
</ul>
</li>
<li><a href="types.html#_short-hand-syntax">4.14. Short-Hand Syntax</a>
<ul class="sectlevel3">
<li><a href="types.html#_array-short-hand-syntax">4.14.1. Array Short-Hand Syntax</a></li>
<li><a href="types.html#_iterablen-short-hand-syntax">4.14.2. IterableN Short-Hand Syntax</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="classifiers.html#_classifiers">5. Classifiers</a>
<ul class="sectlevel2">
<li><a href="classifiers.html#_n4js-specific-classifiers">5.1. N4JS Specific Classifiers</a>
<ul class="sectlevel3">
<li><a href="classifiers.html#_properties-2">5.1.1. Properties</a></li>
<li><a href="classifiers.html#_common-semantics-of-classifiers">5.1.2. Common Semantics of Classifiers</a></li>
<li><a href="classifiers.html#_classes">5.1.3. Classes</a>
<ul class="sectlevel4">
<li><a href="classifiers.html#_definition-of-classes">5.1.3.1. Definition of Classes</a>
<ul class="sectlevel5">
<li><a href="classifiers.html#class-syntax">5.1.3.1.1. Syntax</a></li>
<li><a href="classifiers.html#class-properties">5.1.3.1.2. Properties</a></li>
<li><a href="classifiers.html#class-type-inference">5.1.3.1.3. Type Inference</a></li>
</ul>
</li>
<li><a href="classifiers.html#class-semantics">5.1.3.2. Semantics</a></li>
<li><a href="classifiers.html#_final-modifier">5.1.3.3. Final Modifier</a></li>
<li><a href="classifiers.html#_abstract-classes">5.1.3.4. Abstract Classes</a></li>
<li><a href="classifiers.html#_non-instantiable-classes">5.1.3.5. Non-Instantiable Classes</a></li>
<li><a href="classifiers.html#_superclass">5.1.3.6. Superclass</a></li>
</ul>
</li>
<li><a href="classifiers.html#_interfaces">5.1.4. Interfaces</a>
<ul class="sectlevel4">
<li><a href="classifiers.html#_definition-of-interfaces">5.1.4.1. Definition of Interfaces</a>
<ul class="sectlevel5">
<li><a href="classifiers.html#interfaces-syntax">5.1.4.1.1. Syntax</a></li>
<li><a href="classifiers.html#interfaces-properties">5.1.4.1.2. Properties</a></li>
<li><a href="classifiers.html#interfaces-type-inference">5.1.4.1.3. Type Inference</a></li>
<li><a href="classifiers.html#interfaces-semantics">5.1.4.1.4. Semantics</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="classifiers.html#_generic-classifiers">5.1.5. Generic Classifiers</a></li>
<li><a href="classifiers.html#sec:definition-site-variance">5.1.6. Definition-Site Variance</a></li>
</ul>
</li>
<li><a href="classifiers.html#_members">5.2. Members</a>
<ul class="sectlevel3">
<li><a href="classifiers.html#_syntax-4">5.2.1. Syntax</a>
<ul class="sectlevel4">
<li><a href="classifiers.html#_properties-3">5.2.1.1. Properties</a></li>
</ul>
</li>
<li><a href="classifiers.html#_semantics-3">5.2.2. Semantics</a></li>
<li><a href="classifiers.html#_methods">5.2.3. Methods</a>
<ul class="sectlevel4">
<li><a href="classifiers.html#_syntax-5">5.2.3.1. Syntax</a></li>
<li><a href="classifiers.html#_properties-4">5.2.3.2. Properties</a></li>
<li><a href="classifiers.html#_semantics-4">5.2.3.3. Semantics</a></li>
<li><a href="classifiers.html#_final-methods">5.2.3.4. Final Methods</a></li>
<li><a href="classifiers.html#_abstract-methods">5.2.3.5. Abstract Methods</a></li>
<li><a href="classifiers.html#_generic-methods">5.2.3.6. Generic Methods</a></li>
</ul>
</li>
<li><a href="classifiers.html#_default-methods-in-interfaces">5.2.4. Default Methods in Interfaces</a>
<ul class="sectlevel4">
<li><a href="classifiers.html#_asynchronous-methods">5.2.4.1. Asynchronous Methods</a></li>
</ul>
</li>
<li><a href="classifiers.html#_constructors">5.2.5. Constructors</a>
<ul class="sectlevel4">
<li><a href="classifiers.html#_structural-this-type-in-constructor">5.2.5.1. Structural This Type in Constructor</a></li>
<li><a href="classifiers.html#spec-constructor">5.2.5.2. @Spec Constructor</a></li>
<li><a href="classifiers.html#_callable-constructors">5.2.5.3. Callable Constructors</a></li>
<li><a href="classifiers.html#_covariant-constructors">5.2.5.4. Covariant Constructors</a></li>
</ul>
</li>
<li><a href="classifiers.html#_data-fields">5.2.6. Data Fields</a>
<ul class="sectlevel4">
<li><a href="classifiers.html#data-fields-syntax">5.2.6.1. Syntax</a></li>
<li><a href="classifiers.html#data-fields-properties">5.2.6.2. Properties</a>
<ul class="sectlevel5">
<li><a href="classifiers.html#data-fields-semantics">5.2.6.2.1. Semantics</a></li>
<li><a href="classifiers.html#data-fields-type-inference">5.2.6.2.2. Type Inference</a></li>
</ul>
</li>
<li><a href="classifiers.html#_assignment-modifiers">5.2.6.3. Assignment Modifiers</a></li>
<li><a href="classifiers.html#_field-accessors-getter-setter">5.2.6.4. Field Accessors (Getter/Setter)</a>
<ul class="sectlevel5">
<li><a href="classifiers.html#field-acessors-syntax">5.2.6.4.1. Syntax</a></li>
<li><a href="classifiers.html#field-acessors-properties">5.2.6.4.2. Properties</a></li>
<li><a href="classifiers.html#field-accessors-semantics">5.2.6.4.3. Semantics</a></li>
</ul>
</li>
<li><a href="classifiers.html#optional-fields">5.2.6.5. Optional Fields</a>
<ul class="sectlevel5">
<li><a href="classifiers.html#_syntax-6">5.2.6.5.1. Syntax</a></li>
<li><a href="classifiers.html#_semantics-5">5.2.6.5.2. Semantics</a></li>
<li><a href="classifiers.html#_background">5.2.6.5.3. Background</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="classifiers.html#_static-members">5.2.7. Static Members</a>
<ul class="sectlevel4">
<li><a href="classifiers.html#_access-from-and-to-static-members">5.2.7.1. Access From and To Static Members</a></li>
<li><a href="classifiers.html#_generic-static-methods">5.2.7.2. Generic static methods</a></li>
<li><a href="classifiers.html#_static-members-of-interfaces">5.2.7.3. Static Members of Interfaces</a></li>
</ul>
</li>
<li><a href="classifiers.html#_redefinition-of-members">5.2.8. Redefinition of Members</a>
<ul class="sectlevel4">
<li><a href="classifiers.html#_overriding-of-members">5.2.8.1. Overriding of Members</a></li>
<li><a href="classifiers.html#_implementation-of-members">5.2.8.2. Implementation of Members</a>
<ul class="sectlevel5">
<li><a href="classifiers.html#_member-consumption">5.2.8.2.1. Member Consumption</a></li>
<li><a href="classifiers.html#_member-implementation">5.2.8.2.2. Member Implementation</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="classifiers.html#_structural-typing">5.3. Structural Typing</a>
<ul class="sectlevel3">
<li><a href="classifiers.html#_syntax-7">5.3.1. Syntax</a></li>
<li><a href="classifiers.html#_definition-site-structural-typing">5.3.2. Definition Site Structural Typing</a></li>
<li><a href="classifiers.html#_use-site-structural-typing">5.3.3. Use-Site Structural Typing</a></li>
<li><a href="classifiers.html#structural-readWriteInit-field-typing">5.3.4. Structural Read-only, Write-only and Initializer Field Typing</a></li>
<li><a href="classifiers.html#_public-setter-annotated-with-code-providesinitializer-code">5.3.5. Public Setter Annotated With <code>ProvidesInitializer</code></a></li>
<li><a href="classifiers.html#_structural-types-with-optional-fields">5.3.6. Structural Types With Optional Fields</a></li>
<li><a href="classifiers.html#_structural-types-with-access-modifier">5.3.7. Structural Types With Access Modifier</a></li>
<li><a href="classifiers.html#_structural-types-with-additional-members">5.3.8. Structural Types With Additional Members</a>
<ul class="sectlevel4">
<li><a href="classifiers.html#_syntax-8">5.3.8.1. Syntax</a>
<ul class="sectlevel5">
<li><a href="classifiers.html#_semantics-6">5.3.8.1.1. Semantics</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="functions.html#_functions">6. Functions</a>
<ul class="sectlevel2">
<li><a href="functions.html#_function-type">6.1. Function Type</a>
<ul class="sectlevel3">
<li><a href="functions.html#_properties-5">6.1.1. Properties</a></li>
<li><a href="functions.html#function-type-inference">6.1.2. Type Inference</a></li>
<li><a href="functions.html#_autoboxing-of-function-type">6.1.3. Autoboxing of Function Type</a></li>
<li><a href="functions.html#_arguments-object">6.1.4. Arguments Object</a></li>
</ul>
</li>
<li><a href="functions.html#_ecmascript-5-function-definition">6.2. ECMAScript 5 Function Definition</a>
<ul class="sectlevel3">
<li><a href="functions.html#_function-declaration">6.2.1. Function Declaration</a>
<ul class="sectlevel4">
<li><a href="functions.html#_syntax-9">6.2.1.1. Syntax</a></li>
<li><a href="functions.html#_semantics-8">6.2.1.2. Semantics</a></li>
</ul>
</li>
<li><a href="functions.html#_function-expression">6.2.2. Function Expression</a>
<ul class="sectlevel4">
<li><a href="functions.html#function-expression-syntax">6.2.2.1. Syntax</a></li>
<li><a href="functions.html#_semantics-and-type-inference">6.2.2.2. Semantics and Type Inference</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="functions.html#_ecmascript-2015-function-definition">6.3. ECMAScript 2015 Function Definition</a>
<ul class="sectlevel3">
<li><a href="functions.html#_formal-parameters">6.3.1. Formal Parameters</a>
<ul class="sectlevel4">
<li><a href="functions.html#Type_Modifiers_Optional">6.3.1.1. Optional Parameters</a></li>
<li><a href="functions.html#Type_Modifiers_Default">6.3.1.2. Default Parameters</a></li>
<li><a href="functions.html#Type_Modifiers_Variadic">6.3.1.3. Variadic</a></li>
</ul>
</li>
<li><a href="functions.html#_generator-functions">6.3.2. Generator Functions</a>
<ul class="sectlevel4">
<li><a href="functions.html#generator-functions-syntax">6.3.2.1. Syntax</a></li>
<li><a href="functions.html#generator-functions-semantics">6.3.2.2. Semantics</a></li>
<li><a href="functions.html#_generator-arrow-functions">6.3.2.3. Generator Arrow Functions</a></li>
</ul>
</li>
<li><a href="functions.html#_arrow-function-expression">6.3.3. Arrow Function Expression</a>
<ul class="sectlevel4">
<li><a href="functions.html#arrow-function-expression-syntax">6.3.3.1. Syntax</a></li>
<li><a href="functions.html#arrow-function-expression-semantics-and-type-inference">6.3.3.2. Semantics and Type Inference</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="functions.html#_ecmascript-proposals-function-definition">6.4. ECMAScript Proposals Function Definition</a>
<ul class="sectlevel3">
<li><a href="functions.html#_asynchronous-functions">6.4.1. Asynchronous Functions</a>
<ul class="sectlevel4">
<li><a href="functions.html#asynchronous-functions-syntax">6.4.1.1. Syntax</a></li>
<li><a href="functions.html#asynchronous-functions-semantics">6.4.1.2. Semantics</a></li>
<li><a href="functions.html#_asynchronous-arrow-functions">6.4.1.3. Asynchronous Arrow Functions</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="functions.html#_n4js-extended-function-definition">6.5. N4JS Extended Function Definition</a>
<ul class="sectlevel3">
<li><a href="functions.html#_generic-functions">6.5.1. Generic Functions</a></li>
<li><a href="functions.html#_promisifiable-functions">6.5.2. Promisifiable Functions</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="conversions_and_reflection.html#_conversions-and-reflection">7. Conversions and Reflection</a>
<ul class="sectlevel2">
<li><a href="conversions_and_reflection.html#_autoboxing-and-coercing">7.1. Autoboxing and Coercing</a>
<ul class="sectlevel3">
<li><a href="conversions_and_reflection.html#_coercing">7.1.1. Coercing</a></li>
<li><a href="conversions_and_reflection.html#_autoboxing-of-primitives">7.1.2. Autoboxing of Primitives</a></li>
<li><a href="conversions_and_reflection.html#_autoboxing-of-function-expressions-and-declarations">7.1.3. Autoboxing of Function Expressions and Declarations</a></li>
</ul>
</li>
<li><a href="conversions_and_reflection.html#_auto-conversion-of-objects">7.2. Auto-Conversion of Objects</a>
<ul class="sectlevel3">
<li><a href="conversions_and_reflection.html#_auto-conversion-of-class-instances">7.2.1. Auto-Conversion of Class Instances</a>
<ul class="sectlevel4">
<li><a href="conversions_and_reflection.html#_auto-conversion-of-interface-instances">7.2.1.1. Auto-Conversion of Interface Instances</a></li>
</ul>
</li>
<li><a href="conversions_and_reflection.html#_auto-conversion-of-enum-literals">7.2.2. Auto-Conversion of Enum Literals</a></li>
</ul>
</li>
<li><a href="conversions_and_reflection.html#_type-cast-and-type-check">7.3. Type Cast and Type Check</a>
<ul class="sectlevel3">
<li><a href="conversions_and_reflection.html#_type-cast">7.3.1. Type Cast</a></li>
<li><a href="conversions_and_reflection.html#_type-check">7.3.2. Type Check</a></li>
</ul>
</li>
<li><a href="conversions_and_reflection.html#_reflection-meta-information">7.4. Reflection meta-information</a>
<ul class="sectlevel3">
<li><a href="conversions_and_reflection.html#_reflection-for-classes">7.4.1. Reflection for Classes</a></li>
<li><a href="conversions_and_reflection.html#_reflection-for-interfaces">7.4.2. Reflection for Interfaces</a></li>
<li><a href="conversions_and_reflection.html#_reflection-for-enumerations">7.4.3. Reflection for Enumerations</a></li>
</ul>
</li>
<li><a href="conversions_and_reflection.html#_conversion-of-primitive-types">7.5. Conversion of primitive types</a></li>
</ul>
</li>
<li><a href="expressions.html#_expressions">8. Expressions</a>
<ul class="sectlevel2">
<li><a href="expressions.html#_ecmascript-5-expressions">8.1. ECMAScript 5 Expressions</a>
<ul class="sectlevel3">
<li><a href="expressions.html#_the-this-literal">8.1.1. The this Literal</a></li>
<li><a href="expressions.html#_identifier">8.1.2. Identifier</a></li>
<li><a href="expressions.html#_literals">8.1.3. Literals</a>
<ul class="sectlevel4">
<li><a href="expressions.html#_integer-literals">8.1.3.1. Integer Literals</a></li>
</ul>
</li>
<li><a href="expressions.html#_array-literal">8.1.4. Array Literal</a></li>
<li><a href="expressions.html#_object-literal">8.1.5. Object Literal</a>
<ul class="sectlevel4">
<li><a href="expressions.html#_properties-6">8.1.5.1. Properties</a></li>
<li><a href="expressions.html#_scoping-and-linking">8.1.5.2. Scoping and linking</a></li>
</ul>
</li>
<li><a href="expressions.html#_parenthesized-expression-and-grouping-operator">8.1.6. Parenthesized Expression and Grouping Operator</a></li>
<li><a href="expressions.html#_property-accessors">8.1.7. Property Accessors</a>
<ul class="sectlevel4">
<li><a href="expressions.html#properties-1">8.1.7.1. Properties</a></li>
</ul>
</li>
<li><a href="expressions.html#_new-expression">8.1.8. New Expression</a></li>
<li><a href="expressions.html#_function-expression-2">8.1.9. Function Expression</a></li>
<li><a href="expressions.html#_function-calls">8.1.10. Function Calls</a></li>
<li><a href="expressions.html#_postfix-expression">8.1.11. Postfix Expression</a></li>
<li><a href="expressions.html#_unary-expression">8.1.12. Unary Expression</a></li>
<li><a href="expressions.html#_multiplicative-expression">8.1.13. Multiplicative Expression</a></li>
<li><a href="expressions.html#_additive-expression">8.1.14. Additive Expression</a>
<ul class="sectlevel4">
<li><a href="expressions.html#type-inference-10">8.1.14.1. Type Inference</a></li>
</ul>
</li>
<li><a href="expressions.html#_bitwise-shift-expression">8.1.15. Bitwise Shift Expression</a></li>
<li><a href="expressions.html#_relational-expression">8.1.16. Relational Expression</a></li>
<li><a href="expressions.html#_equality-expression">8.1.17. Equality Expression</a></li>
<li><a href="expressions.html#_binary-bitwise-expression">8.1.18. Binary Bitwise Expression</a></li>
<li><a href="expressions.html#_binary-logical-expression">8.1.19. Binary Logical Expression</a></li>
<li><a href="expressions.html#_conditional-expression">8.1.20. Conditional Expression</a></li>
<li><a href="expressions.html#_assignment-expression">8.1.21. Assignment Expression</a></li>
<li><a href="expressions.html#_comma-expression">8.1.22. Comma Expression</a></li>
</ul>
</li>
<li><a href="expressions.html#_ecmascript-6-expressions">8.2. ECMAScript 6 Expressions</a>
<ul class="sectlevel3">
<li><a href="expressions.html#_the-super-keyword">8.2.1. The super Keyword</a></li>
</ul>
</li>
<li><a href="expressions.html#_ecmascript-7-expressions">8.3. ECMAScript 7 Expressions</a>
<ul class="sectlevel3">
<li><a href="expressions.html#_await-expression">8.3.1. Await Expression</a></li>
</ul>
</li>
<li><a href="expressions.html#_n4js-specific-expressions">8.4. N4JS Specific Expressions</a>
<ul class="sectlevel3">
<li><a href="expressions.html#_class-expression">8.4.1. Class Expression</a></li>
<li><a href="expressions.html#_cast-as-expression">8.4.2. Cast (As) Expression</a>
<ul class="sectlevel4">
<li><a href="expressions.html#cast-as-expression-semantics-type-inference">8.4.2.1. Semantics and Type Inference</a></li>
</ul>
</li>
<li><a href="expressions.html#Import_Calls">8.4.3. Import Calls</a></li>
</ul>
</li>
<li><a href="expressions.html#compile-time-expressions">8.5. Compile-Time Expressions</a></li>
</ul>
</li>
<li><a href="statements.html#_statements">9. Statements</a>
<ul class="sectlevel2">
<li><a href="statements.html#_ecmascript-5-statements">9.1. ECMAScript 5 Statements</a>
<ul class="sectlevel3">
<li><a href="statements.html#_function-or-field-accessor-bodies">9.1.1. Function or Field Accessor Bodies</a></li>
<li><a href="statements.html#_variable-statement">9.1.2. Variable Statement</a></li>
<li><a href="statements.html#_if-statement">9.1.3. If Statement</a></li>
<li><a href="statements.html#_iteration-statements">9.1.4. Iteration Statements</a></li>
<li><a href="statements.html#_return-statement">9.1.5. Return Statement</a></li>
<li><a href="statements.html#_with-statement">9.1.6. With Statement</a></li>
<li><a href="statements.html#_switch-statement">9.1.7. Switch Statement</a></li>
<li><a href="statements.html#_throw-try-and-catch-statements">9.1.8. Throw, Try, and Catch Statements</a></li>
<li><a href="statements.html#_debugger-statement">9.1.9. Debugger Statement</a></li>
</ul>
</li>
<li><a href="statements.html#_ecmascript-6-statements">9.2. ECMAScript 6 Statements</a>
<ul class="sectlevel3">
<li><a href="statements.html#_let">9.2.1. Let</a></li>
<li><a href="statements.html#_const">9.2.2. Const</a></li>
<li><a href="statements.html#_for-of-statement">9.2.3. <code>for &#8230;&#8203; of</code> statement</a></li>
<li><a href="statements.html#_import-statement">9.2.4. Import Statement</a>
<ul class="sectlevel4">
<li><a href="statements.html#Dynamic_Imports">9.2.4.1. Dynamic Imports</a></li>
<li><a href="statements.html#_immutabilaty-of-imports">9.2.4.2. Immutabilaty of Imports</a></li>
</ul>
</li>
<li><a href="statements.html#_export-statement">9.2.5. Export Statement</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="annotations.html#_annotations">10. Annotations</a>
<ul class="sectlevel2">
<li><a href="annotations.html#_introduction-2">10.1. Introduction</a>
<ul class="sectlevel3">
<li><a href="annotations.html#_syntax-13">10.1.1. Syntax</a></li>
<li><a href="annotations.html#_properties-7">10.1.2. Properties</a></li>
<li><a href="annotations.html#_element-specific-annotations">10.1.3. Element-Specific Annotations</a></li>
<li><a href="annotations.html#_general-annotations">10.1.4. General Annotations</a>
<ul class="sectlevel4">
<li><a href="annotations.html#_idebug">10.1.4.1. IDEBUG</a></li>
</ul>
</li>
<li><a href="annotations.html#idebug-syntax">10.1.5. Syntax</a>
<ul class="sectlevel4">
<li><a href="annotations.html#_semantics-11">10.1.5.1. Semantics</a></li>
<li><a href="annotations.html#_suppress-warnings">10.1.5.2. Suppress Warnings</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="annotations.html#_declaration-of-annotations">10.2. Declaration of Annotations</a></li>
</ul>
</li>
<li><a href="#_extended-fetaures">11. Extended Fetaures</a>
<ul class="sectlevel2">
<li><a href="#_array-and-object-destructuring">11.1. Array and Object Destructuring</a>
<ul class="sectlevel3">
<li><a href="#_syntax-14">11.1.1. Syntax</a></li>
<li><a href="#_semantics-12">11.1.2. Semantics</a></li>
</ul>
</li>
<li><a href="#_dependency-injection">11.2. Dependency Injection</a>
<ul class="sectlevel3">
<li><a href="#_di-components-and-injectors">11.2.1. DI Components and Injectors</a>
<ul class="sectlevel4">
<li><a href="#_dicomponent-relations">11.2.1.1. DIComponent Relations</a></li>
</ul>
</li>
<li><a href="#_binders-and-bindings">11.2.2. Binders and Bindings</a></li>
<li><a href="#_injection-points">11.2.3. Injection Points</a>
<ul class="sectlevel4">
<li><a href="#_field-injection">11.2.3.1. Field Injection</a></li>
<li><a href="#_constructor-injection">11.2.3.2. Constructor Injection</a></li>
<li><a href="#_method-injection">11.2.3.3. Method Injection</a>
<ul class="sectlevel5">
<li><a href="#_provider">11.2.3.3.1. Provider</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#_n4js-di-life-cycle-and-scopes">11.2.4. N4JS DI Life Cycle and Scopes</a>
<ul class="sectlevel4">
<li><a href="#_injection-cylces">11.2.4.1. Injection Cylces</a></li>
<li><a href="#_default-scope">11.2.4.2. Default Scope</a></li>
<li><a href="#_singleton-scope">11.2.4.3. Singleton Scope</a></li>
<li><a href="#_per-injection-chain-singleton">11.2.4.4. Per Injection Chain Singleton</a></li>
</ul>
</li>
<li><a href="#_validation-of-callsites-targeting-n4injector-methods">11.2.5. Validation of callsites targeting N4Injector methods</a></li>
<li><a href="#_n4js-di-annotations">11.2.6. N4JS DI Annotations</a>
<ul class="sectlevel4">
<li><a href="#_n4js-di-generateinjector">11.2.6.1. N4JS DI @GenerateInjector</a></li>
<li><a href="#_n4js-di-withparentinjector">11.2.6.2. N4JS DI @WithParentInjector</a></li>
<li><a href="#_n4js-di-usebinder">11.2.6.3. N4JS DI @UseBinder</a></li>
<li><a href="#_n4js-di-binder">11.2.6.4. N4JS DI @Binder</a></li>
<li><a href="#_n4js-di-bind">11.2.6.5. N4JS DI @Bind</a></li>
<li><a href="#_n4js-di-provides">11.2.6.6. N4JS DI @Provides</a></li>
<li><a href="#_n4js-di-inject">11.2.6.7. N4JS DI @Inject</a></li>
<li><a href="#_n4js-di-singleton">11.2.6.8. N4JS DI @Singleton</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#_test-support">11.3. Test Support</a></li>
<li><a href="#_polyfill-definitions">11.4. Polyfill Definitions</a>
<ul class="sectlevel3">
<li><a href="#_runtime-polyfill-definitions">11.4.1. Runtime Polyfill Definitions</a></li>
<li><a href="#_static-polyfill-definitions">11.4.2. Static Polyfill Definitions</a></li>
<li><a href="#_transpiling-static-polyfilled-classes">11.4.3. Transpiling static polyfilled classes</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="components.html#_components">12. Components</a>
<ul class="sectlevel2">
<li><a href="components.html#_overview-2">12.1. Overview</a></li>
<li><a href="components.html#Component_Types">12.2. Component Types</a>
<ul class="sectlevel3">
<li><a href="components.html#_libraries">12.2.1. Libraries</a></li>
<li><a href="components.html#_runtime-environment-and-runtime-libraries">12.2.2. Runtime Environment and Runtime Libraries</a></li>
<li><a href="components.html#_tests">12.2.3. Tests</a></li>
<li><a href="components.html#_type-definitions">12.2.4. Type Definitions</a></li>
</ul>
</li>
<li><a href="components.html#package-json">12.3. Package.json File</a>
<ul class="sectlevel3">
<li><a href="components.html#_basic-properties">12.3.1. Basic Properties</a></li>
<li><a href="components.html#_n4js-properties">12.3.2. N4JS Properties</a></li>
<li><a href="components.html#_constraints">12.3.3. Constraints</a></li>
</ul>
</li>
<li><a href="components.html#_support-for-npm-scopes">12.4. Support for NPM Scopes</a></li>
<li><a href="components.html#sec:N4JS-Type-Definitions">12.5. N4JS Type Definitions</a>
<ul class="sectlevel3">
<li><a href="components.html#_specify-type-definition">12.5.1. Specify Type Definition</a></li>
<li><a href="components.html#_name-conventions">12.5.2. Name Conventions</a></li>
<li><a href="components.html#_version-conventions">12.5.3. Version Conventions</a>
<ul class="sectlevel4">
<li><a href="components.html#_define-a-new-type-definition-package">12.5.3.1. Define a New Type Definition Package</a></li>
<li><a href="components.html#_using-a-type-definition-package">12.5.3.2. Using a Type Definition Package</a></li>
<li><a href="components.html#_rational">12.5.3.3. Rational</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="components.html#_modules">12.6. Modules</a></li>
<li><a href="components.html#_api-and-implementation-component">12.7. API and Implementation Component</a>
<ul class="sectlevel3">
<li><a href="components.html#_execution-of-api-and-implementation-components">12.7.1. Execution of API and Implementation Components</a></li>
<li><a href="components.html#_api-and-implementation-with-di">12.7.2. API and Implementation With DI</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="plainjs.html#_plainjs">13. PlainJS</a>
<ul class="sectlevel2">
<li><a href="plainjs.html#_type-inference-and-validation-for-plain-js">13.1. Type Inference and Validation for Plain JS</a></li>
<li><a href="plainjs.html#_external-declarations">13.2. External Declarations</a>
<ul class="sectlevel3">
<li><a href="plainjs.html#_declaring-externals">13.2.1. Declaring externals</a></li>
<li><a href="plainjs.html#_instantiating-external-classes">13.2.2. Instantiating external classes</a></li>
<li><a href="plainjs.html#_implementation-of-external-declarations">13.2.3. Implementation of External Declarations</a></li>
<li><a href="plainjs.html#_example">13.2.4. Example</a></li>
</ul>
</li>
<li><a href="plainjs.html#_global-definitions">13.3. Global Definitions</a></li>
<li><a href="plainjs.html#_runtime-definitions">13.4. Runtime Definitions</a></li>
<li><a href="plainjs.html#_applying-polyfills">13.5. Applying Polyfills</a></li>
</ul>
</li>
<li><a href="jsdoc.html#_jsdoc-2">14. JSDoc</a>
<ul class="sectlevel2">
<li><a href="jsdoc.html#_general-n4jsdoc-features">14.1. General N4JSDoc Features</a>
<ul class="sectlevel3">
<li><a href="jsdoc.html#_provided-inline-tags">14.1.1. Provided Inline Tags</a>
<ul class="sectlevel4">
<li><a href="jsdoc.html#jsdoc_tag__code">14.1.1.1. @code</a></li>
<li><a href="jsdoc.html#jsdoc_tag__link">14.1.1.2. @link</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="jsdoc.html#_n4jsdoc-for-user-projects">14.2. N4JSdoc for User Projects</a>
<ul class="sectlevel3">
<li><a href="jsdoc.html#_standard-tags">14.2.1. Standard Tags</a>
<ul class="sectlevel4">
<li><a href="jsdoc.html#_-author">14.2.1.1. @author</a></li>
<li><a href="jsdoc.html#jsdoc_tag_param">14.2.1.2. @param</a></li>
<li><a href="jsdoc.html#jsdoc_tag_return">14.2.1.3. @return</a></li>
</ul>
</li>
<li><a href="jsdoc.html#_test-related-tags">14.2.2. Test Related Tags</a>
<ul class="sectlevel4">
<li><a href="jsdoc.html#jsdoc_tag__testee">14.2.2.1. @testee</a></li>
<li><a href="jsdoc.html#jsdoc_tag__testeeFromType">14.2.2.2. @testeeFromType</a></li>
<li><a href="jsdoc.html#_testeeType_and__testeeMember">14.2.2.3. @testeeType and @testeeMember</a></li>
<li><a href="jsdoc.html#jsdoc_tag_reqid_in_Tests">14.2.2.4. @reqid in Tests</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="jsdoc.html#_n4jsdoc-for-api-and-implementation-projects">14.3. N4JSDoc for API and Implementation Projects</a>
<ul class="sectlevel3">
<li><a href="jsdoc.html#jsdoc_tag__apiNote">14.3.1. @apiNote</a></li>
<li><a href="jsdoc.html#API_Project_Tags">14.3.2. API Project Tags</a>
<ul class="sectlevel4">
<li><a href="jsdoc.html#jsdoc_tag_apiState">14.3.2.1. @apiState</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="jsx.html#_jsx">15. JSX</a>
<ul class="sectlevel2">
<li><a href="jsx.html#_jsx-support">15.1. JSX Support</a></li>
<li><a href="jsx.html#_jsx-backend">15.2. JSX Backend</a></li>
</ul>
</li>
<li><a href="grammars.html#_grammars">16. Grammars</a>
<ul class="sectlevel2">
<li><a href="grammars.html#_type-expressions-grammar">16.1. Type Expressions Grammar</a></li>
<li><a href="grammars.html#_n4js-language-grammar">16.2. N4JS Language Grammar</a></li>
</ul>
</li>
<li><a href="jsobjects.html#_jsobjects">17. JSObjects</a>
<ul class="sectlevel2">
<li><a href="jsobjects.html#_object">17.1. Object</a></li>
<li><a href="jsobjects.html#_string">17.2. String</a></li>
<li><a href="jsobjects.html#_boolean">17.3. Boolean</a></li>
<li><a href="jsobjects.html#_number">17.4. Number</a>
<ul class="sectlevel3">
<li><a href="jsobjects.html#_static-attributes">17.4.1. Static Attributes</a></li>
</ul>
</li>
<li><a href="jsobjects.html#function">17.5. Function</a></li>
<li><a href="jsobjects.html#_error">17.6. Error</a></li>
<li><a href="jsobjects.html#_array">17.7. Array</a></li>
<li><a href="jsobjects.html#_date">17.8. Date</a></li>
<li><a href="jsobjects.html#_math">17.9. Math</a>
<ul class="sectlevel3">
<li><a href="jsobjects.html#static-attributes-1">17.9.1. Static Attributes</a></li>
</ul>
</li>
<li><a href="jsobjects.html#_regexp">17.10. RegExp</a></li>
<li><a href="jsobjects.html#_json">17.11. JSON</a></li>
</ul>
</li>
<li><a href="n4js_objects.html#_n4js-objects">18. N4JS Objects</a>
<ul class="sectlevel2">
<li><a href="n4js_objects.html#_reflection-model">18.1. Reflection Model</a></li>
<li><a href="n4js_objects.html#_error-types">18.2. Error Types</a>
<ul class="sectlevel3">
<li><a href="n4js_objects.html#_n4apinotimplemented">18.2.1. N4ApiNotImplemented</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="appendix_a_acronyms.html#_acronyms">Appendix A: Acronyms</a></li>
<li><a href="appendix_b_license.html#sec:License">Appendix B: License</a></li>
<li><a href="appendix_c_bibliography.html#_bibliography">Appendix C: Bibliography</a></li>
</ul>
</div>
</div>
<div id="content"><div class="sect1">
<h2 id="_extended-fetaures"><a class="anchor" href="#_extended-fetaures"></a><a class="link" href="#_extended-fetaures">11. Extended Fetaures</a></h2>
<div class="sectionbody">
<div class="sect2 language-n4js">
<h3 id="_array-and-object-destructuring"><a class="anchor" href="#_array-and-object-destructuring"></a><a class="link" href="#_array-and-object-destructuring">11.1. Array and Object Destructuring</a></h3>
<div class="paragraph">
<p>N4JS supports array and object destructuring as provided in ES6.
This is used to conveniently assign selected elements of an array or object to a number of newly-declared or pre-existing variables or to further destructure them by using nested
destructuring patterns <sup class="footnote">[<a id="_footnoteref_55" class="footnote" href="appendix_c_bibliography.html#_footnote_55" title="View footnote.">55</a>]</sup>.</p>
</div>
<div class="sect3">
<h4 id="_syntax-14"><a class="anchor" href="#_syntax-14"></a><a class="link" href="#_syntax-14">11.1.1. Syntax</a></h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ebnf" data-lang="ebnf">BindingPattern &lt;Yield&gt;:
    ObjectBindingPattern&lt;Yield&gt;
    | ArrayBindingPattern&lt;Yield&gt;
;

ObjectBindingPattern &lt;Yield&gt; returns BindingPattern:
    {BindingPattern}
    '{' (properties+=BindingProperty&lt;Yield,AllowType=false&gt; (',' properties+=BindingProperty&lt;Yield,AllowType=false&gt;)*)? '}'
;

ArrayBindingPattern &lt;Yield&gt; returns BindingPattern:
    {BindingPattern}
    '['
        elements+=Elision* (
            elements+=BindingRestElement&lt;Yield&gt;
            (',' elements+=Elision* elements+=BindingRestElement&lt;Yield&gt;)*
            (',' elements+=Elision*)?
        )?
    ']'
;

BindingProperty &lt;Yield, AllowType&gt;:
      =&gt;(LiteralBindingPropertyName&lt;Yield&gt; ':') value=BindingElement&lt;Yield&gt;
    | value=SingleNameBinding&lt;Yield,AllowType&gt;
;

fragment LiteralBindingPropertyName &lt;Yield&gt;*:
    declaredName=IdentifierName | declaredName=STRING | declaredName=NumericLiteralAsString
    // this is added here due to special treatment for a known set of expressions
    | '[' (declaredName=SymbolLiteralComputedName&lt;Yield&gt; | declaredName=STRING) ']'
;</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_semantics-12"><a class="anchor" href="#_semantics-12"></a><a class="link" href="#_semantics-12">11.1.2. Semantics</a></h4>
<div class="paragraph">
<p>The following example declares four variables <code>a</code>, <code>b</code>, <code>x</code>, and <code>prop2</code>. Variables <code>a</code> and <code>x</code> will have the value <code>hello</code>, whereas <code>b</code> and <code>prop2</code> will have value 42.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">var [a,b] = ["hello", 42];

var {prop1:x, prop2} = {prop1:"hello", prop2:42};</code></pre>
</div>
</div>
<div class="paragraph">
<p>In the case of <code>prop2</code>, we do not provide a property name and variable name separately; this is useful in cases where the property name also makes for a
suitable variable name (called <code>single name binding</code>).</p>
</div>
<div class="paragraph">
<p>One of the most useful use cases of destructuring is in a <code>for..of</code> loop.
Take this example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">var arr1 = [ ["hello",1,2,3], ["goodbye",4,5,6] ];
for(var [head,...tail] of arr1) {
    console.log(head,'/',tail);
}
// will print:
//   hello / [ 1, 2, 3 ]
//   goodbye / [ 4, 5, 6 ]

var arr2 = [ {key:"hello", value:42}, {key:"goodbye", value:43} ];
for(var {key,value} of arr2) {
    console.log(key,'/',value);
}
// will print:
//   hello / 42
//   goodbye / 43</code></pre>
</div>
</div>
<div class="paragraph">
<p>Array and object destructuring pattern can appear in many different places:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>In a variable declaration (not just in variable statements but also in other places where variable declarations are allowed, e.g. plain for loops; called <em>destructuring binding</em>; see <a href="statements.html#_variable-statement">Variable Statement</a>).</p>
</li>
<li>
<p>On the left-hand side of an assignment expression (the assignment expression is then called <em>destructuring assignment</em>; see <a href="expressions.html#_assignment-expression">Assignment Expression</a>).</p>
</li>
<li>
<p>In a <code>for..in</code> or <code>for..of</code> loop on the left side of the <code>in</code>/<code>of</code> (see <a href="statements.html#_for-of-statement"><code>for &#8230;&#8203; of</code> statement</a>).</p>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title=""></i>
</td>
<td class="content">
It can also be used in plain statements, but then we actually have one of the above two use cases.
</td>
</tr>
</table>
</div>
</li>
<li>
<p>With lists of formal parameters or function arguments (not supported yet).</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>For further details on array and object destructuring please refer to the ECMAScript 6 specification - [<a href="appendix_c_bibliography.html#ECMA15a">ECMA15a</a>].</p>
</div>
<div class="paragraph">
<p>Type annotations can only be added when a new variable name is introduced since the short version would be ambiguous with the long one.
For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">var {x: someTypeOrNewVar} = ol</code></pre>
</div>
</div>
<div class="paragraph">
<p>could either mean that a new variable <code>someTypeOrNewVar</code> is declared and <code>ol.x</code> is assigned to it, or that a new variable <code>x</code> is declared with type <code>someTypeOrNewVar</code>.
The longer form would look like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">var {x: x: someType} = ol</code></pre>
</div>
</div>
<div class="paragraph">
<p>We can make this more readable:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">var {propOfOl: newVar: typeOfNewVar} = ol</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2 language-n4js">
<h3 id="_dependency-injection"><a class="anchor" href="#_dependency-injection"></a><a class="link" href="#_dependency-injection">11.2. Dependency Injection</a></h3>
<div class="paragraph">
<p>This chapter describes <a href="appendix_a_acronyms.html#_acronyms">DI</a> mechanisms for N4JS.
This includes compiler, validation and language extensions that allow to achieve DI mechanisms built in into the N4JS language and IDE.</p>
</div>
<div class="paragraph">
<p>N4JS <a href="appendix_a_acronyms.html#_acronyms">DI</a> support specifies a means for obtaining objects in such a way as to maximize reusability, testability and maintainability,
especially compared to traditional approaches such as constructors, factories and service locators.
While this can be achieved manually (without tooling support) it is difficult for nontrivial applications.
The solutions that DI provides should empower N4JS users to achieve the above goals without the burden of maintaining so-called ’boilerplate’ code.</p>
</div>
<div id="fig-di-terms" class="imageblock" style="text-align: center">
<div class="content">
<img src="chapters/11_extFeatures/fig/diBasicTerms.png" alt="diBasicTerms">
</div>
<div class="title">Figure 8. DI Basic Terms</div>
</div>
<div class="paragraph">
<p><em>key: pass the dependency instead of letting the client create or find it</em></p>
</div>
<div class="paragraph">
<p>Core terms</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>Service</strong> - A set of APIs describing the functionality of the service.</p>
</li>
<li>
<p><strong>Service Implementation</strong>s - One or more implementations of given service API.</p>
</li>
<li>
<p><strong>Client</strong> - Consumer of a given functionality, uses the given <strong>Service Implementation</strong>.</p>
</li>
<li>
<p><strong>Injector</strong> - Object providing <strong>Service Implementation</strong> of a specific <strong>Service</strong>, according to configuration.</p>
</li>
<li>
<p><strong>Binding</strong> - Part of configuration describing which interface implementing a subtype will be injected, when a given interface is requested.</p>
</li>
<li>
<p><strong>Provider</strong> - Factory used to create instances of a given <strong>Service Implementation</strong> or its sub-components, can be a method.</p>
</li>
<li>
<p><strong>Injection Point</strong> - Part of the user’s code that will have the given dependency injected. This is usually fields, method parameters, constructor parameters etc.</p>
</li>
<li>
<p><strong>DI configuration</strong> - This describes which elements of the user’s code are used in mechanisms and how they are wired.
It is derived from user code elements being marked with appropriate annotations, bindings and providers.</p>
</li>
<li>
<p><strong>di wiring</strong> - The code responsible for creating user objects.
These are injectors, type factories/providers, fields initiators etc.</p>
</li>
</ul>
</div>
<div class="sect3">
<h4 id="_di-components-and-injectors"><a class="anchor" href="#_di-components-and-injectors"></a><a class="link" href="#_di-components-and-injectors">11.2.1. DI Components and Injectors</a></h4>
<div class="paragraph">
<p>N4JS’ <a href="#_dependency-injection">Dependency Injection</a> systems is based on the notion of <a href="appendix_a_acronyms.html#_acronyms">DIC</a>.</p>
</div>
<div class="openblock definition">
<div class="content">
<div class="paragraph">
<p><a id="di_component"></a><strong>Definition:</strong> <a href="#di_component">DI Component</a></p>
</div>
<div class="paragraph">
<p>A <a href="appendix_a_acronyms.html#_acronyms">DIC</a> is a N4Class annotated with <code>@GenerateInjector</code>.</p>
</div>
</div>
</div>
<div class="paragraph">
<p>This annotation causes an <em>injector</em> to be created for (and associated to) the <a href="appendix_a_acronyms.html#_acronyms">DI</a>.
DIC can be composed; meaning that when requested to inject an instance of a type, a DIC’s injector can delegate this request to the injector of the containing DIC.
An injector always prioritizes its own configuration before delegating to the container’s injector.
For validation purposes, a child DI can be annotated with <code>@WithParent</code> to ensure that it is always used with a proper parent.</p>
</div>
<div class="paragraph">
<p><em>Injector</em> is the main object of DI mechanisms responsible for creating object graphs of the application.
At runtime, injectors are instances of <code>N4Injector</code>.</p>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-138"></a><strong>Req. IDE-138:</strong> <a href="#Req-IDE-138">DI Component and Injector</a> (ver. 1)</p>
</div>
<div class="paragraph">
<p>The following constraints must hold for a class <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi></math> marked as DIC:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>A subclass <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>S</mi></math> of <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi></math> is a DIC as well and it must be marked with <code>GenerateInjector</code>.</p>
</li>
<li>
<p>If a parent <a href="#_dicomponent-relations">DIC</a> <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>P</mi></math> is specified via <code>WithParent</code>, then <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>P</mi></math> must be a DIC as well.</p>
</li>
<li>
<p>The injector associated to a DIC is of type <code>N4Injector</code>. It can be retrieved via <code>N4Injector.of(DIC)</code> in which <code>DIC</code> is the <code>DIC</code>.</p>
</li>
<li>
<p>Injectors associated to DIC a are DI-singletons (cf. <a href="#_singleton-scope">Singleton Scope</a>).
Two calls to <code>N4Injector.of(DIC)</code> are different (as different DIC are assumed).</p>
</li>
</ol>
</div>
</div>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-139"></a><strong>Req. IDE-139:</strong> <a href="#Req-IDE-139">Injection Phase</a> (ver. 1)</p>
</div>
<div class="paragraph">
<p>We call the (transitive) creation and setting of values by an injector <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>I</mi></math> caused by the creation of an root object <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>R</mi></math> the <em>injection phase</em>.
If an instance <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi></math> is newly created by the injector <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>I</mi></math> (regardless of the injection point being used), the injection is transitively applied on <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi></math>.
The following constraints have to hold:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Root objects are created by one of the following mechanisms:</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>Any class or interface can be created as root objects via an injector associated to a DIC:<br>
<code>var x: X = N4Injector.of(DIC).create(X);</code><br>
in which <code>DIC</code> is a DIC.</p>
<div class="paragraph">
<p>Of course, an appropriate binding must exist. <sup class="footnote">[<a id="_footnoteref_56" class="footnote" href="appendix_c_bibliography.html#_footnote_56" title="View footnote.">56</a>]</sup></p>
</div>
</li>
<li>
<p>If a type has the injector being injected, e.g. via field injection <code>@Inject injector: N4Injector;</code>, then this injector can be used anytime in the control flow to create
a new root object similar as above (using <code>create</code> method).</p>
</li>
<li>
<p>If a provider has been injected (i.e. an instance of <code>{N4Provider}</code>), then its <code>get()</code> method can be used to create a root object causing a new injection phase to take place.</p>
</li>
</ol>
</div>
</li>
<li>
<p>If <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi><mo>.</mo><mi>c</mi><mi>t</mi><mi>o</mi><mi>r</mi></math> is marked as injection point, all its arguments are set by the injector.
This is also true for an inherited constructor marked as an injection point.
See <a href="#Req-IDE-143">[Req-IDE-143]</a> . For all arguments the injection phase constraints have to hold as well.</p>
</li>
<li>
<p>All fields of <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi></math>, including <em>inherited</em> once, marked as injection points are set by the injector.
For all fields the injection phase constraints have to hold as well.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>The injector may use a provider method (of a binder) to create nested instances.</p>
</div>
<div class="paragraph">
<p>The injector is configured with <em>Binders</em> and it tracks <em>Bindings</em> between types (<a href="#_binders-and-bindings">Binders and Bindings</a>).
An N4JS developer normally would not interact with this object directly except when defining an entry-point to his application.
<em>Injector</em>s are configured with <em>Binder</em>s which contain explicit <em>Binding</em>s defined by an N4JS developer.
A set of these combined with <em>implicit bindings</em> creates the <em>di configuration</em> used by a given injector.
To configure given <em>Injector</em>s with given <em>Binder</em>(s) use <code>@UseBinder</code> annotation.</p>
</div>
</div>
</div>
<div class="sect4">
<h5 id="_dicomponent-relations"><a class="anchor" href="#_dicomponent-relations"></a><a class="link" href="#_dicomponent-relations">11.2.1.1. DIComponent Relations</a></h5>
<div class="paragraph">
<p>A Parent-Child relation can be established between two DIComponents.
Child DIComponents use the parent bindings but can also be configured with their own bindings or <em>change</em> targets used by a parent.
The final circumstance is local to the child and is referred to as <em>rebinding</em>.
For more information about bindings see <a href="#_binders-and-bindings">Binders and Bindings</a>.
A Child-Parent relation is expressed by the <code>@WithParentInjector</code> annotation attached to a given DIComponent.
When this relation is defined between DIComponents, the user needs to take care to preserve the proper relation between injectors.
In other words, the user must provide an instance of the parent injector (the injector of the DIComponent passes as a parameter to <code>@WithParentInjector</code>) when creating the child injector
(injector of the DIComponent annotated with <code>@WithParentInjector</code>).</p>
</div>
<div class="exampleblock">
<div class="title">Example 99. Simple DIComponents Relation</div>
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">@GenerateInjector
class ParentDIComponent{}

@GenerateInjector
@WithParentInjector(ParentDIComponent)
class ChildDIComponent{}

var parentInejctor = N4Inejctor.of(ParentDiCompoennt);
var childInjector = N4Inejctor.of(ChildDIComponent, parentInjector);</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>With complex DIComponent structures, injector instances can be created with a directly-declared parent and also with any of its children.
This is due to the fact that any child can rebind types, add new bindings, but not remove them.
Any child is, therefore, <em>compatible</em> with its parents.</p>
</div>
<div class="openblock definition">
<div class="content">
<div class="paragraph">
<p><a id="compatible_dicomponent"></a><strong>Definition:</strong> <a href="#compatible_dicomponent">Compatible DIComponent</a></p>
</div>
<div class="paragraph">
<p>A given DIComponent is compatible with another DIComponent if it has bindings for all keys in other component bindings.</p>
</div>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mo>∃</mo><mi>D</mi><mi>I</mi><mi>C</mi><mn>1</mn><mo>,</mo><mi>D</mi><mi>I</mi><mi>C</mi><mn>2</mn><mi>:</mi><mi>D</mi><mi>I</mi><mi>C</mi><mn>1.</mn><mover accent="true"><mrow><mi>b</mi><mi>i</mi><mi>n</mi><mi>d</mi><mi>i</mi><mi>n</mi><mi>g</mi></mrow><mo>¯</mo></mover><mo>.</mo><mover accent="true"><mrow><mi>k</mi><mi>e</mi><mi>y</mi></mrow><mo>¯</mo></mover><mo>⇒</mo><mi>D</mi><mi>I</mi><mi>C</mi><mn>2.</mn><mover accent="true"><mrow><mi>b</mi><mi>i</mi><mi>n</mi><mi>d</mi><mi>i</mi><mi>n</mi><mi>g</mi></mrow><mo>¯</mo></mover><mo>.</mo><mover accent="true"><mrow><mi>k</mi><mi>e</mi><mi>y</mi></mrow><mo>¯</mo></mover><mo>⇔</mo><mi>D</mi><mi>I</mi><mi>C</mi><mn>2</mn><mspace width="1.0mm"/><mo>&lt;</mo><mstyle mathvariant="monospace"><mtext>:</mtext></mstyle><mspace width="1.0mm"/><mi>D</mi><mi>I</mi><mi>C</mi><mn>1</mn></math>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title=""></i>
</td>
<td class="content">
Although subtype notation <math xmlns="http://www.w3.org/1998/Math/MathML"><mspace width="1.0mm"/><mo>&lt;</mo><mstyle mathvariant="monospace"><mtext>:</mtext></mstyle><mspace width="1.0mm"/></math> is used here it does <strong>not</strong> imply actual subtype relations.
It was used in this instance for of lack of formal notations for DI concepts and because this is similar to the Liskov Substitution principle.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>A complex Child-Parent relation between components is depicted in <a href="#fig-complex-dicomponents-relations">Complex DIComponents Relations</a> and <a href="#ex:complex-dicomponents-relations">Complex DIComponents Relations</a> below.</p>
</div>
<div id="fig-complex-dicomponents-relations" class="imageblock" style="text-align: center">
<div class="content">
<img src="chapters/11_extFeatures/fig/diagDICParentChild.svg" alt="diagDICParentChild">
</div>
<div class="title">Figure 9. Complex DIComponents Relations</div>
</div>
</div>
</div>
<div id="ex:complex-dicomponents-relations" class="exampleblock">
<div class="title">Example 100. Complex DIComponents Relations</div>
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">@GenerateInjector class A {}
@GenerateInjector @WithParentInjector(A) class B {}
@GenerateInjector @WithParentInjector(B) class C {}
@GenerateInjector @WithParentInjector(C) class D {}
@GenerateInjector @WithParentInjector(A) class B2 {}
@GenerateInjector @WithParentInjector(B2) class C2 {}
@GenerateInjector @WithParentInjector(C2) class D2 {}
@GenerateInjector @WithParentInjector(A) class X {}
@GenerateInjector @WithParentInjector(C) class Y {}

// creating injectors
var injectorA = N4Injector.of(A);
//following throws DIConfigurationError, expected parent is not provided
//var injectorB =  N4Injector.of(B);
//correct declarations
var injectorB =  N4Injector.of(B, injectorA);
var injectorC = N4Injector.of(C, injectorB);
var injectorD = N4Injector.of(D, injectorC);
var injectorB2 = N4Injector.of(B2, injectorA);
var injectorC2 = N4Injector.of(C2, injectorB2);
var injectorD2 = N4Injector.of(D2, injectorC2);

//Any injector of {A,B,C,D,b2,C2,D2} s valid parent for injector of X, e.g. D or D2
N4Injector.of(X, injectorD);//is ok as compatible parent is provided
N4Injector.of(X, injectorD2);//is ok as compatible parent is provided

N4Injector.of(Y, injectorC);//is ok as direct parent is provided
N4Injector.of(Y, injectorD);//is ok as compatible parent is provided

N4Injector.of(Y, injectorB2);//throws DIConfigurationError, incompatible parent is provided
N4Injector.of(Y, injectorC2);//throws DIConfigurationError, incompatible parent is provided
N4Injector.of(Y, injectorD2);//throws DIConfigurationError, incompatible parent is provided</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_binders-and-bindings"><a class="anchor" href="#_binders-and-bindings"></a><a class="link" href="#_binders-and-bindings">11.2.2. Binders and Bindings</a></h4>
<div class="paragraph">
<p><em>Binder</em> allows an N4JS developer to (explicitly) define a set of <em>Binding</em>s that will be used by an <em>Injector</em> configured with a given <em>Binder</em>.
There are two ways for <em>Binder</em> to define <em>Binding</em>s: <code>@Bind</code> (<a href="#_n4js-di-bind">N4JS DI @Bind</a>) annotations and a method annotated with <code>@Provides</code>.</p>
</div>
<div class="paragraph">
<p><em>Binder</em> is declared by annotating a class with the <code>@Binder</code> annotation.</p>
</div>
<div class="paragraph">
<p>A <em>Binding</em> is part of a configuration that defines which instance of
what type should be injected into an <em>injection point</em> (<a href="#_injection-points">Injection Points</a>) with an expected type.</p>
</div>
<div class="paragraph">
<p><em>Provider Method</em> is essentially a <em>factory method</em> that is used to create an instance of a type.
N4JS allows a developer to declare those methods (see <a href="#_n4js-di-provides">N4JS DI @Provides</a>) which gives them a hook in instance creation process.
Those methods will be used when creating instances by the <em>Injector</em> configured with the corresponding <em>Binder</em>.
A provider method is a special kind of binding (<math xmlns="http://www.w3.org/1998/Math/MathML"><mi>k</mi><mi>e</mi><mi>y</mi></math>) in which the return type of the method is the <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>k</mi><mi>e</mi><mi>y</mi></math>.
The <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi></math> type is unknown at compile time (although it may be inferred by examining the return statements of the provide method).</p>
</div>
<div class="openblock definition">
<div class="content">
<div class="paragraph">
<p><a id="binding"></a><strong>Definition:</strong> <a href="#binding">Binding</a></p>
</div>
<div class="paragraph">
<p>A <em>binding</em> is a pair <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>b</mi><mi>i</mi><mi>n</mi><mi>d</mi><mfenced close=")" open="("><mrow><mi>k</mi><mi>e</mi><mi>y</mi></mrow><mrow><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi></mrow></mfenced></math>.
It defines that for a dependency with a given key which usually is the expected type at the injection point.
An instance of type <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi></math> is injected.</p>
</div>
<div class="paragraph">
<p>A <em>binding</em> is called <em>explicit</em> if it is declared in the code, i.e. via <code>@Bind</code>
annotation or <code>@Provides</code> annotation).</p>
</div>
<div class="paragraph">
<p>A <em>binding</em> is called <em>implicit</em> if it is not declared.
An implicit binding can only be used if the <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>k</mi><mi>e</mi><mi>y</mi></math> is a class and derived from the type at the injection point, i.e. the type of the field or parameter to be injected.
In that case, the <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi></math> equals the <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>k</mi><mi>e</mi><mi>y</mi></math>.</p>
</div>
<div class="paragraph">
<p>A provider method <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>M</mi></math> (in the binder) defines a binding</p>
</div>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mi>b</mi><mi>i</mi><mi>n</mi><mi>d</mi><mfenced close=")" open="("><mrow><mi>M</mi><mo>.</mo><mi>r</mi><mi>e</mi><mi>t</mi><mi>u</mi><mi>r</mi><mi>n</mi><mi>T</mi><mi>y</mi><mi>p</mi><mi>e</mi></mrow><mi>X</mi></mfenced></math>
</div>
</div>
<div class="paragraph">
<p>(in which <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>X</mi></math> is an existential type with <math xmlns="http://www.w3.org/1998/Math/MathML"><mo>∃</mo><mi>X</mi><mspace width="1.0mm"/><mo>&lt;</mo><mstyle mathvariant="monospace"><mtext>:</mtext></mstyle><mspace width="1.0mm"/><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi><mo>.</mo><mi>r</mi><mi>e</mi><mi>t</mi><mi>u</mi><mi>r</mi><mi>n</mi><mi>T</mi><mi>y</mi><mi>p</mi><mi>e</mi></math>).</p>
</div>
<div class="paragraph">
<p>For simplification, we define:</p>
</div>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mtable><mtr><mtd><mi>k</mi><mi>e</mi><mi>y</mi><mo>*</mo><mo>=</mo><mfenced close="" open="{"><mtable><mtr><mtd><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi><mo>.</mo><mi>r</mi><mi>e</mi><mi>t</mi><mi>u</mi><mi>r</mi><mi>n</mi><mi>T</mi><mi>y</mi><mi>p</mi><mi>e</mi><mo>,</mo></mtd><mtd><mstyle mathvariant="bold"><mtext>if target is provider method</mtext></mstyle></mtd></mtr><mtr><mtd><mi>k</mi><mi>e</mi><mi>y</mi><mo>,</mo></mtd><mtd><mstyle mathvariant="bold"><mtext>otherwise (key is a type reference)</mtext></mstyle></mtd></mtr></mtable></mfenced></mtd></mtr></mtable></math>
</div>
</div>
<div class="paragraph">
<p>and</p>
</div>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mtable><mtr><mtd><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi><mo>*</mo><mo>=</mo><mfenced close="" open="{"><mtable><mtr><mtd><mi>X</mi><mspace width="1.0mm"/><mo>&lt;</mo><mstyle mathvariant="monospace"><mtext>:</mtext></mstyle><mspace width="1.0mm"/><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi><mo>.</mo><mi>r</mi><mi>e</mi><mi>t</mi><mi>u</mi><mi>r</mi><mi>n</mi><mi>T</mi><mi>y</mi><mi>p</mi><mi>e</mi><mo>,</mo></mtd><mtd><mstyle mathvariant="bold"><mtext>if target is provider method</mtext></mstyle></mtd></mtr><mtr><mtd><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi><mo>,</mo></mtd><mtd><mstyle mathvariant="bold"><mtext>otherwise (target is a type reference)</mtext></mstyle></mtd></mtr></mtable></mfenced></mtd></mtr></mtable></math>
</div>
</div>
</div>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-140"></a><strong>Req. IDE-140:</strong> <a href="#Req-IDE-140">Bindings</a> (ver. 1)</p>
</div>
<div class="paragraph">
<p>For a given binding <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>b</mi><mo>=</mo><mfenced close=")" open="("><mrow><mi>k</mi><mi>e</mi><mi>y</mi></mrow><mrow><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi></mrow></mfenced></math>, the following constraints must hold: <sup class="footnote">[<a id="_footnoteref_57" class="footnote" href="appendix_c_bibliography.html#_footnote_57" title="View footnote.">57</a>]</sup></p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>k</mi><mi>e</mi><mi>y</mi></math> must be either a class or an interface.</p>
</li>
<li>
<p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi></math> must either be a class or a provider method.</p>
</li>
<li>
<p>If <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>b</mi></math> is implicit, then <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>k</mi><mi>e</mi><mi>y</mi></math> must be a class.
If <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>k</mi><mi>e</mi><mi>y</mi></math> references a type <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>T</mi></math>, then <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi><mo>=</mo><mi>T</mi></math> – even if <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>k</mi><mi>e</mi><mi>y</mi></math> is a use-site structural type.</p>
</li>
<li>
<p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>k</mi><mi>e</mi><mi>y</mi></math> and <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi><mo>*</mo></math> can be nominal, structural or field-structural types, either definition-site or use-site.
The injector and binder needs to take the different structural reference into account at runtime!</p>
</li>
<li>
<p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><mi>t</mi><mo>*</mo><mspace width="1.0mm"/><mo>&lt;</mo><mstyle mathvariant="monospace"><mtext>:</mtext></mstyle><mspace width="1.0mm"/><mi>k</mi><mi>e</mi><mi>y</mi></math> must hold</p>
</li>
<li>
<p>If during injection phase no binding for a given key is found, an <code>DIUnsatisfiedBindingError</code> is thrown.</p>
</li>
</ol>
</div>
</div>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-141"></a><strong>Req. IDE-141:</strong> <a href="#Req-IDE-141">Transitive Bindings</a> (ver. 1)</p>
</div>
<div class="paragraph">
<p>If an injector contains two given bindings <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>b</mi><mn>1</mn></msub><mo>=</mo><mfenced close=")" open="("><mrow><mi>k</mi><mi>e</mi><msub><mi>y</mi><mn>1</mn></msub></mrow><mrow><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><msub><mi>t</mi><mn>1</mn></msub></mrow></mfenced></math> and
<math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>b</mi><mn>2</mn></msub><mo>=</mo><mfenced close=")" open="("><mrow><mi>k</mi><mi>e</mi><msub><mi>y</mi><mn>2</mn></msub></mrow><mrow><mi>k</mi><mi>e</mi><msub><mi>y</mi><mn>1</mn></msub></mrow></mfenced></math>, an effective binding
<math xmlns="http://www.w3.org/1998/Math/MathML"><mi>b</mi><mo>=</mo><mfenced close=")" open="("><mrow><mi>k</mi><mi>e</mi><msub><mi>y</mi><mn>2</mn></msub></mrow><mrow><mi>t</mi><mi>a</mi><mi>r</mi><mi>g</mi><mi>e</mi><msub><mi>t</mi><mn>1</mn></msub></mrow></mfenced></math> is derived (replacing
<math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>b</mi><mn>1</mn></msub></math>).</p>
</div>
<div class="paragraph">
<p>N4JS <a href="appendix_a_acronyms.html#_acronyms">DI</a> mechanisms don’t allow for injection of primitives or built-in types.
Only user-defined N4Types can be used. In cases where a user needs to inject a primitive or a built-in type, the developer must wrap it into its own
class <sup class="footnote">[<a id="_footnoteref_58" class="footnote" href="appendix_c_bibliography.html#_footnote_58" title="View footnote.">58</a>]</sup>.
This is to say that none of the following metatypes can be bound: primitive types, enumerations, functions, object types, union- or intersection types. It is possible to (implicitly) bind to built-in classes.</p>
</div>
<div class="paragraph">
<p>While direct binding overriding or rebinding is not allowed, <em>Injector</em> can be configured in a way where one type can be separately bound to different types with implicit binding,
<em>explicit binding</em> and in bindings of the child injectors.
<em>Binding precedence</em> is a mechanism of <em>Injector</em> selecting a binding use for a type.
It operates in the following order:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Try to use explicit binding, if this is not available:</p>
</li>
<li>
<p>Try to delegate to parent injectors (order of lookup is not guaranteed, first found is selected). If this is not available then:</p>
</li>
<li>
<p>Try to use use implicit binding, which is simply to attempt to create the instance.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>If no binding for a requested type is available an error will be thrown.</p>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_injection-points"><a class="anchor" href="#_injection-points"></a><a class="link" href="#_injection-points">11.2.3. Injection Points</a></h4>
<div class="paragraph">
<p>By <em>injection point</em> we mean a place in the source code which, at runtime, will be expected to hold a reference to a particular type instance.</p>
</div>
<div class="sect4">
<h5 id="_field-injection"><a class="anchor" href="#_field-injection"></a><a class="link" href="#_field-injection">11.2.3.1. Field Injection</a></h5>
<div class="paragraph">
<p>In its simplest form, this is a class field annotated with <code>@Inject</code> annotation.
At runtime, an instance of the containing class will be expected to hold reference to an instance of the field declared type.
Usually that case
is called <em>Field Injection</em>.</p>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-142"></a><strong>Req. IDE-142:</strong> <a href="#Req-IDE-142">Field Injection</a> (ver. 1)</p>
</div>
<div class="paragraph">
<p>The injector will inject the
following fields:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>All directly contained fields annotated with <code>@Inject</code>.</p>
</li>
<li>
<p>All inherited fields annotated with <code>@Inject</code>.</p>
</li>
<li>
<p>The injected fields will be created by the injector and their fields will be injected as well.</p>
</li>
</ol>
</div>
</div>
</div>
<div class="exampleblock">
<div class="title">Example 101. Simple Field Injection</div>
<div class="content">
<div class="paragraph">
<p><a href="#ex:field-injection">Simple Field Injection</a> demonstrates simple field injection using default bindings.
Note that all inherited fields (i.e. <code>A.xInA</code>) are injected and also fields in injected fields (i.e. <code>x.y</code>)</p>
</div>
<div id="ex:field-injection" class="listingblock">
<div class="title">Simple Field Injection</div>
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">class X {
    @Inject y: Y;
}
class Y {}

class A {
    @Inject xInA: X;
}
class B extends A {
    @Inject xInB: X;
}

@GenerateInjector
export public class DIC {
    @Inject a: B;
}

var dic = N4Injector.of(DIC).create(DIC);
console.log(dic);              // --&gt; DIC
console.log(dic.a);            // --&gt; B
console.log(dic.a.xInA);       // --&gt; X
console.log(dic.a.xInA.y);     // --&gt; Y
console.log(dic.a.xInB);       // --&gt; X
console.log(dic.a.xInB.y);     // --&gt; Y</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="_constructor-injection"><a class="anchor" href="#_constructor-injection"></a><a class="link" href="#_constructor-injection">11.2.3.2. Constructor Injection</a></h5>
<div class="paragraph">
<p>Parameters of the constructor can also be injected, in which case this is usually referred to as <em>Constructor Inejction</em>.
This is similar to <em>Method Injection</em> and while constructor injection is supported in N4JS, method injection is not (see remarks below).</p>
</div>
<div class="paragraph">
<p>When a constructor is annotated with <code>@Inject</code> annotation, all user-defined, non-generic types given as the parameters will be injected into the instance’s constructor created by the dependency injection framework.
Currently, optional constructor parameters are always initialized and created by the framework, therefore, they are ensured to be available at the constructor invocation time.
Unlike optional parameters, variadic parameters cannot be injected into a type’s constructor.
In case of annotating a constructor with <code>@Inject</code> that has variadic parameters, a validation error will be reported.
When a class’s constructor is annotated with <code>@Inject</code> annotation, it is highly recommended to annotate all explicitly-defined constructors at the subclass level.
If this is not done, the injection chain can break and runtime errors might occur due to undefined constructor parameters.
In the case of a possible broken injection chain due to missing <code>@Inject</code> annotations for any subclasses, a validation warning will
be reported.</p>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-143"></a><strong>Req. IDE-143:</strong> <a href="#Req-IDE-143">Constructor Injection</a> (ver. 1)</p>
</div>
<div class="paragraph">
<p>If a class <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi></math> has a constructor marked as injection point, the
following applies:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>If <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi></math> is subclassed by <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>S</mi></math>, and if <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>S</mi></math> has no explicit constructor, then <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>S</mi></math> inherits the constructor from <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi></math> and it will be an injection point handled by the injector during injection phase.</p>
</li>
<li>
<p>If <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>S</mi></math> provides its own injector, <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi><mo>.</mo><mi>c</mi><mi>t</mi><mi>o</mi><mi>r</mi></math> is no longer recognized by the injector during the injection phase.
There will be a warning generated in <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>S</mi><mo>.</mo><mi>c</mi><mi>t</mi><mi>o</mi><mi>r</mi></math> to mark it as injection point as well in order to prevent inconsistent injection behavior.
Still, <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>C</mi><mo>.</mo><mi>c</mi><mi>t</mi><mi>o</mi><mi>r</mi></math> must be called in <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>S</mi><mo>.</mo><mi>c</mi><mi>t</mi><mi>o</mi><mi>r</mi></math> similarly to other overridden constructors.</p>
</li>
</ol>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="_method-injection"><a class="anchor" href="#_method-injection"></a><a class="link" href="#_method-injection">11.2.3.3. Method Injection</a></h5>
<div class="paragraph">
<p>Other kinds of injector points are method parameters where (usually) all method parameters are injected when the method is called.
In a way, constructor injection is a special case of the method itself.</p>
</div>
<div class="sect5">
<h6 id="_provider"><a class="anchor" href="#_provider"></a><a class="link" href="#_provider">11.2.3.3.1. Provider</a></h6>
<div class="paragraph">
<p><em>Provider</em> is essentially a <em>factory</em> for a given type.
By injecting an <code>N4Provider</code> into any injection point, one can acquire new instances of a given type provided by the injected provider.
The providers prove useful when one has to solve re-injection issues since the depended type can be wired and injected via the provider rather than the dependency itself and can therefore obtain
new instances from it if required.
Provider can be also used as a means of delaying the instantiation time of a given type.</p>
</div>
<div class="paragraph">
<p><code>N4Provider</code> is a public generic built-in interface that is used to support the re-injection.
The generic type represents the dependent type that has to be obtained.
The <code>N4Provider</code> interface has one single public method: <code>public T get()</code> which should be invoked from the client code when a new instance of the dependent type is required.
Unlike any other unbound interfaces, the <code>N4Provider</code> can be injected without any explicit binding.</p>
</div>
<div class="paragraph">
<p>The following snippet demonstrates the usage of <code>N4Provider</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">class SomeService { }

@Singleton
class SomeSingletonService { }

class SomeClass {

    @Inject serviceProvider: N4Provider&lt;SomeService&gt;;
    @Inject singletonServiceProvider: N4Provider&lt;SomeSingletonService&gt;;

    void foo() {
        console.log(serviceProvider.get() ===
            serviceProvider.get()); //false

        console.log(singletonServiceProvider.get() ===
            singletonServiceProvider.get()); //true
    }

}</code></pre>
</div>
</div>
<div class="paragraph">
<p>It is important to note that the <code>N4Provider</code> interface can be extended by any user-defined interfaces and/or can be implemented by any user-defined classes.
For those user-defined providers, consider all binding-related rules; the extended interface, for example, must be explicitly bound via a binder to be injected.
The binding can be omitted only for the built-in <code>N4Provider</code>s.</p>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_n4js-di-life-cycle-and-scopes"><a class="anchor" href="#_n4js-di-life-cycle-and-scopes"></a><a class="link" href="#_n4js-di-life-cycle-and-scopes">11.2.4. N4JS DI Life Cycle and Scopes</a></h4>
<div class="paragraph">
<p><a href="appendix_a_acronyms.html#_acronyms">DI</a> Life Cycle defines when a new instance is created by the injector as its destruction is handled by JavaScript.
The creation depends on the scope of the type.
Aside from the scopes, note that it is also possible to implement custom scopes and life cycle management via <code>N4JSProvider</code> and <code>Binder@Provides</code> methods.</p>
</div>
<div class="sect4">
<h5 id="_injection-cylces"><a class="anchor" href="#_injection-cylces"></a><a class="link" href="#_injection-cylces">11.2.4.1. Injection Cylces</a></h5>
<div class="openblock definition">
<div class="content">
<div class="paragraph">
<p><a id="injection_cycle"></a><strong>Definition:</strong> <a href="#injection_cycle">Injection Cycle</a></p>
</div>
<div class="paragraph">
<p>We define an injection graph <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>G</mi><mfenced close=")" open="("><mi>V</mi><mi>E</mi></mfenced></math> as a directed graph as follows: <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>V</mi></math> (the vertices) is the set types of which instances are created during the injection phase and which use .
<math xmlns="http://www.w3.org/1998/Math/MathML"><mi>E</mi></math> (the edges) is a set of directed and labeled edges <math xmlns="http://www.w3.org/1998/Math/MathML"><mfenced close=")" open="("><msub><mi>v</mi><mn>1</mn></msub><msub><mi>v</mi><mn>2</mn></msub><mrow><mi>l</mi><mi>a</mi><mi>b</mi><mi>e</mi><mi>l</mi></mrow></mfenced></math>, where label indicates the injection point:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p><math xmlns="http://www.w3.org/1998/Math/MathML"><mfenced close=")" open="("><msub><mi>T</mi><mi>o</mi></msub><msub><mi>T</mi><mi>f</mi></msub><mrow><mi>"</mi><mi>f</mi><mi>i</mi><mi>e</mi><mi>l</mi><mi>d</mi><mi>"</mi></mrow></mfenced></math>, if <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>T</mi><mi>f</mi></msub></math> is the actualy type of an an injected field of an instance of type <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>T</mi><mi>o</mi></msub></math></p>
</li>
<li>
<p><math xmlns="http://www.w3.org/1998/Math/MathML"><mfenced close=")" open="("><msub><mi>T</mi><mi>c</mi></msub><msub><mi>T</mi><mi>p</mi></msub><mrow><mi>"</mi><mi>c</mi><mi>t</mi><mi>o</mi><mi>r</mi><mi>"</mi></mrow></mfenced></math>, if <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>T</mi><mi>p</mi></msub></math> is the type of a parameter used in a constructor injection of type <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>T</mi><mi>c</mi></msub></math></p>
</li>
</ol>
</div>
<div class="paragraph">
<p>One cycle in this graph is an injection cycle.</p>
</div>
</div>
</div>
<div class="paragraph">
<p>When injecting instances into an object, cycles have to be detected and handled independently from the scope.
If this is not done, the following examples would result in an infinite loop causing the entire script to freeze until the engine reports an error:</p>
</div>
<table class="tableblock frame-none grid-rows spread">
<colgroup>
<col style="width: 57.1428%;">
<col style="width: 42.8572%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-bottom"><div><div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">class A { @Inject b: B; }
class B { @Inject a: A; }</code></pre>
</div>
</div></div></td>
<td class="tableblock halign-center valign-top"><div><div id="fig-field-cycle" class="imageblock" style="text-align: center">
<div class="content">
<img src="chapters/11_extFeatures/fig/injectionGraph_cycleField.svg" alt="injectionGraph cycleField">
</div>
<div class="title">Figure 10. Field Cycle</div>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-bottom"><div><div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">class C { @Inject constructor(d: D) {} }
class D { @Inject c: C; }</code></pre>
</div>
</div></div></td>
<td class="tableblock halign-center valign-top"><div><div id="fig-ctor-field" class="imageblock" style="text-align: center">
<div class="content">
<img src="chapters/11_extFeatures/fig/injectionGraph_cycleCtorField.svg" alt="injectionGraph cycleCtorField">
</div>
<div class="title">Figure 10. Ctor Field Cycle</div>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-bottom"><div><div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">class E { @Inject constructor(f: F) {} }
class F { @Inject constructor(e: E) {} }</code></pre>
</div>
</div></div></td>
<td class="tableblock halign-center valign-top"><div><div id="fig-ctor-cycle" class="imageblock" style="text-align: center">
<div class="content">
<img src="chapters/11_extFeatures/fig/injectionGraph_cycleCtor.svg" alt="injectionGraph cycleCtor">
</div>
<div class="title">Figure 10. Ctor Cycle</div>
</div></div></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>The injector needs to detect these cycles and resolve them.</p>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-144"></a><strong>Req. IDE-144:</strong> <a href="#Req-IDE-144">Resolution of Injection Cycles</a> (ver. 1)</p>
</div>
<div class="paragraph">
<p>A cycle <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>c</mi><mo>⊂</mo><mi>G</mi></math>, with <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>G</mi></math> being an injection graph, is resolved as follows:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>If <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>c</mi></math> contains no edge with <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>l</mi><mi>a</mi><mi>b</mi><mi>e</mi><mi>l</mi><mo>=</mo><mi>"</mi><mi>c</mi><mi>t</mi><mi>o</mi><mi>r</mi><mi>"</mi></math>, the cycle is resolved using the algorithm described below.</p>
</li>
<li>
<p>If <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>c</mi></math> contains at least one edge with <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>l</mi><mi>a</mi><mi>b</mi><mi>e</mi><mi>l</mi><mo>=</mo><mi>"</mi><mi>c</mi><mi>t</mi><mi>o</mi><mi>r</mi><mi>"</mi></math>, a runtime exception is thrown.</p>
</li>
</ol>
</div>
</div>
</div>
<div class="paragraph">
<p>Cycles stemming from field injection are resolved by halting the creation of new instances of types which have been already created by a containing instance.
The previously-created instance is then reused.
This makes injecting the instance of a (transitive) container less complicated and without the need to pass the container instance down the entire chain.
The following pseudo code describes the algorithm to create new instances which are injected into a newly created object:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">function injectDependencies(object) {
    doInjectionWithCylceAwareness(object, {(typeof object -&gt; object)})
}

function doInjectionWithCylceAwareness(object, createdInstancesPerType) {
    forall v $\in$ injectedVars of object {
        var type = retrieveBoundType(v)
        var instance = createdInstancesPerType.get(type)
        if (not exists instance) {
            instance = createInstance(type, createdInstancesPerType)
            doInjectionWithCylceAwareness(instance,
                createdInstancesPerType $\cap$ {(type-&gt;instance)})
        }
        v.value = instance;
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The actual instance is created in line 10 via <code>createInstance</code>.
This function then takes scopes into account.
The <code>createdInstancesPerType</code> map is passed to that function in order to enable cycle detection for constructor injection.
The following scopes are supported by the N4JS DI, other scopes, cf. <a href="https://jersey.java.net/documentation/latest/ioc.html">Jersey custom scopes</a> and <a href="https://github.com/google/guice/wiki/CustomScopes">Guice custom scopes</a>, may be added in the future.</p>
</div>
<div class="paragraph">
<p>This algorithm is not working for constructor injection because it is possible to already access all fields of the arguments passed to the constructor.
In the algorithm, however, the instances may not be completely initialized.</p>
</div>
</div>
<div class="sect4">
<h5 id="_default-scope"><a class="anchor" href="#_default-scope"></a><a class="link" href="#_default-scope">11.2.4.2. Default Scope</a></h5>
<div class="paragraph">
<p>The default scope always creates a new instance.</p>
</div>
</div>
<div class="sect4">
<h5 id="_singleton-scope"><a class="anchor" href="#_singleton-scope"></a><a class="link" href="#_singleton-scope">11.2.4.3. Singleton Scope</a></h5>
<div class="paragraph">
<p>The singleton scope (per injector) creates one instance (of the type with <code>@Singleton</code> scope) per injector, which is then shared between clients.</p>
</div>
<div class="paragraph">
<p>The injector will preserve a single instance of the type of <code>S</code> and will provide it to all injection points where type of <code>S</code> is used.
Assuming nested injectors without any declared binding where the second parameter is <code>S</code>, the same preserved singleton instance will be available for all nested injectors at all injection points as well.</p>
</div>
<div class="paragraph">
<p>The singleton preservation behavior changes when explicit bindings are declared for type <code>S</code> on the nested injector level.
Let&#8217;s assume that the type <code>S</code> exists and the type is annotated with <code>@Singleton</code>.
Furthermore, there is a declared binding where the binding&#8217;s second argument is <code>S</code>.
In that case, unlike in other dependency injection frameworks, nested injectors may preserve a singleton for itself and all descendant injectors with <code>@Bind</code> annotation.
In this case, the preserved singleton at the child injector level will be a different instance than the one at the parent injectors.</p>
</div>
<div class="paragraph">
<p>The tables below depict the expected runtime behavior of singletons used at different injector levels.
Assume the following are injectors: <code>C</code>, <code>D</code>, <code>E</code>, <code>F</code> and <code>G</code>. Injector <code>C</code> is the top most injector and its nesting injector <code>D</code>, hence injector <code>C</code> is the parent of the injector <code>D</code>.
Injector <code>D</code> is nesting <code>E</code> and so on.
The most nested injector is <code>G</code>. Let&#8217;s assume <code>J</code> is an interface, class <code>U</code> implements interface <code>J</code> and class <code>V</code> extends class <code>U</code>.
Finally assume both <code>U</code> and <code>V</code> are annotated with <code>@Singleton</code> at definition-site.</p>
</div>
<div class="paragraph">
<p><a href="#tab:diNoBindings">DI No Bindings</a> depicts the singleton preservation for nested injectors without any bindings.
All injectors use the same instance from a type.
Type <code>J</code> is not available at all since it is not bound to any concrete implementation:</p>
</div>
<table id="tab:diNoBindings" class="tableblock frame-all grid-all spread">
<caption class="title">Table 12. DI No Bindings</caption>
<colgroup>
<col style="width: 28.5714%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2858%;">
</colgroup>
<tbody>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">Binding</p></th>
<td class="tableblock halign-center valign-top"></td>
<td class="tableblock halign-center valign-top"></td>
<td class="tableblock halign-center valign-top"></td>
<td class="tableblock halign-center valign-top"></td>
<td class="tableblock halign-center valign-top"></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">Injector nesting (<math xmlns="http://www.w3.org/1998/Math/MathML"><mo>&gt;</mo></math>)</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock">C</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">D</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">E</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">F</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">G</p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">J</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>N</mi><mi>a</mi><mi>N</mi></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>N</mi><mi>a</mi><mi>N</mi></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>N</mi><mi>a</mi><mi>N</mi></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>N</mi><mi>a</mi><mi>N</mi></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>N</mi><mi>a</mi><mi>N</mi></math></p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">U</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">V</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p><a href="#tab:diTransitiveBindings">DI Transitive Bindings</a> is configured by explicit bindings. At the root injector level, type <code>J</code> is bound to type <code>U</code>.
Since the second argument of the binding is declared as a singleton at the definition-site,
this explicit binding implicitly ensures that the injector and all of its descendants preserve a singleton of the bound type <code>U</code>.
At injector level <code>C</code>, <code>D</code> and <code>E</code>, the same instance is used for type <code>J</code> which is type <code>U</code> at runtime.
At injector level <code>E</code> there is an additional binding from type <code>U</code> to type <code>V</code> that overrules the binding declared at the root injector level.
With this binding, each places where <code>J</code> is declared, type <code>U</code> is used at runtime.</p>
</div>
<div class="paragraph">
<p>Furthermore, since <code>V</code> is declared as a singleton, both injector <code>F</code> and <code>G</code> are using a shared singleton instance of type <code>V</code>.
Finally, for type <code>V</code>, injector <code>C</code>, <code>D</code> and <code>E</code> should use a separate instance of <code>V</code> other than injector level <code>F</code> and <code>G</code> because <code>V</code> is preserved at injector level <code>F</code> with the <code>U</code> <math xmlns="http://www.w3.org/1998/Math/MathML"><mo>→</mo></math> <code>V</code> binding.</p>
</div>
<table id="tab:diTransitiveBindings" class="tableblock frame-all grid-all spread">
<caption class="title">Table 13. DI Transitive Bindings</caption>
<colgroup>
<col style="width: 28.5714%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2858%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-center valign-top">Binding</th>
<th class="tableblock halign-center valign-top">J &#8594; U</th>
<th class="tableblock halign-center valign-top"></th>
<th class="tableblock halign-center valign-top"></th>
<th class="tableblock halign-center valign-top">U &#8594; V</th>
<th class="tableblock halign-center valign-top"></th>
</tr>
</thead>
<tbody>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">Injector nesting (&gt;)</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock">C</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">D</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">E</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">F</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">G</p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">J</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">U</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">V</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>1</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>1</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>1</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p><a href="#tab:diReBinding">DI Re - Binding</a> depicts the singleton behaviour but unlike the above
table, the bindings are declared for the interface <code>J</code>.</p>
</div>
<table id="tab:diReBinding" class="tableblock frame-all grid-all spread">
<caption class="title">Table 14. DI Re - Binding</caption>
<colgroup>
<col style="width: 28.5714%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2858%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-center valign-top">Binding</th>
<th class="tableblock halign-center valign-top">J &#8594; U</th>
<th class="tableblock halign-center valign-top"></th>
<th class="tableblock halign-center valign-top"></th>
<th class="tableblock halign-center valign-top">J &#8594; V</th>
<th class="tableblock halign-center valign-top"></th>
</tr>
</thead>
<tbody>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">Injector nesting (<math xmlns="http://www.w3.org/1998/Math/MathML"><mo>&gt;</mo></math>)</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock">C</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">D</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">E</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">F</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">G</p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">J</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">U</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">V</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>1</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>1</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>1</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p><a href="#tab:diChildBinding">DI Child Binding</a> describes the singleton behavior when both bindings are configured at child injector levels but not the root injector level.</p>
</div>
<table id="tab:diChildBinding" class="tableblock frame-all grid-all spread">
<caption class="title">Table 15. DI Child Binding</caption>
<colgroup>
<col style="width: 28.5714%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2857%;">
<col style="width: 14.2858%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-center valign-top">Binding</th>
<th class="tableblock halign-center valign-top"></th>
<th class="tableblock halign-center valign-top">U <math xmlns="http://www.w3.org/1998/Math/MathML"><mo>→</mo></math> V</th>
<th class="tableblock halign-center valign-top"></th>
<th class="tableblock halign-center valign-top">J <math xmlns="http://www.w3.org/1998/Math/MathML"><mo>→</mo></math> U</th>
<th class="tableblock halign-center valign-top"></th>
</tr>
</thead>
<tbody>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">Injector nesting (<math xmlns="http://www.w3.org/1998/Math/MathML"><mo>&gt;</mo></math>)</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock">C</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">D</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">E</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">F</p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock">G</p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">J</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>N</mi><mi>a</mi><mi>N</mi></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>N</mi><mi>a</mi><mi>N</mi></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>N</mi><mi>a</mi><mi>N</mi></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">U</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>1</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>U</mi><mn>0</mn></msub></math></p></td>
</tr>
<tr>
<th class="tableblock halign-center valign-top"><p class="tableblock">V</p></th>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>1</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
<td class="tableblock halign-center valign-top"><p class="tableblock"><math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>V</mi><mn>0</mn></msub></math></p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect4">
<h5 id="_per-injection-chain-singleton"><a class="anchor" href="#_per-injection-chain-singleton"></a><a class="link" href="#_per-injection-chain-singleton">11.2.4.4. Per Injection Chain Singleton</a></h5>
<div class="paragraph">
<p>The per injection chain singleton is ’between’ the default and singleton scope.
It can be used in order to explicitly describe the situation which happens when a simple cycle is resolved automatically.
It has more effects that lead to a more deterministic behavior.</p>
</div>
<div class="paragraph">
<p>Assume a provider declared as</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">var pb: Provider&lt;B&gt;;</code></pre>
</div>
</div>
<div class="paragraph">
<p>to be available:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">@PerInjectionSingleton
class A {  }

class B { @Inject a: A; @Inject a1: A;}

b1=pb.get();
b2=pb.get();
b1.a != b2.a
b1.a == b1.a1
b2.a == b2.a1</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">@Singleton
class A {  }

class B { @Inject a: A; @Inject a1: A;}

b1=pb.get();
b2=pb.get();
b1.a == b2.a
b1.a == b1.a1
b2.a == b2.a1</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">// no annotation
class A {  }

class B { @Inject a A; @Inject a1: A;}

b1=pb.get();
b2=pb.get();
b1.a != b2.a
b1.a != b1.a1
b2.a != b2.a1</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_validation-of-callsites-targeting-n4injector-methods"><a class="anchor" href="#_validation-of-callsites-targeting-n4injector-methods"></a><a class="link" href="#_validation-of-callsites-targeting-n4injector-methods">11.2.5. Validation of callsites targeting N4Injector methods</a></h4>
<div class="paragraph">
<p>Terminology for this section:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>a value is <strong>injectable</strong> if it</p>
<div class="ulist">
<ul>
<li>
<p>either conforms to a user-defined class or interface (a non-parameterized one, that is),</p>
</li>
<li>
<p>or conforms to Provider-of-T where T is injectable itself.</p>
</li>
</ul>
</div>
</li>
<li>
<p>a classifier declaring injected members is said to <strong>require injection</strong></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>To better understand the validations in effect for callsites targeting</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">N4Injector.of(ctorOfDIC: constructor{N4Object}, parentDIC: N4Injector?, ...providedBinders: N4Object)</code></pre>
</div>
</div>
<div class="paragraph">
<p>we can recap that at runtime:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The first argument denotes a DIC constructor.</p>
</li>
<li>
<p>The second (optional) argument is an injector.</p>
</li>
<li>
<p>Lastly, the purpose of <code>providedBinders</code> is as follows:</p>
<div class="ulist">
<ul>
<li>
<p>The DIC above is marked with one or more <code>@UseBinder</code>.</p>
</li>
<li>
<p>Some of those binders may require injection.</p>
</li>
<li>
<p>Some of those binders may have constructor(s) taking parameters.</p>
</li>
<li>
<p>The set of binders described above should match the providedBinders.</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
<div class="paragraph">
<p>Validations in effect for <code>N4Injector.create(type{T} ctor)</code> callsites:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>type{T}</code> should be injectable (in particular, it may be an <code>N4Provider</code>).</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="_n4js-di-annotations"><a class="anchor" href="#_n4js-di-annotations"></a><a class="link" href="#_n4js-di-annotations">11.2.6. N4JS DI Annotations</a></h4>
<div class="paragraph">
<p>Following annotations describe API used to configure N4JSDI.</p>
</div>
<div class="sect4">
<h5 id="_n4js-di-generateinjector"><a class="anchor" href="#_n4js-di-generateinjector"></a><a class="link" href="#_n4js-di-generateinjector">11.2.6.1. N4JS DI @GenerateInjector</a></h5>
<table class="tableblock frame-none grid-none spread">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">name</dt>
<dd>
<p>@GenerateInjector</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">targets</dt>
<dd>
<p>N4Class</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">retention policy</dt>
<dd>
<p>RUNTIME</p>
</dd>
</dl>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">transitive</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">repeatable</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">arguments</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p><code>@GenerateInjector</code> marks a given class as DIComponent of the graph.
The generated injector will be responsible for creating an instance of that class and all of its dependencies.</p>
</div>
</div>
<div class="sect4">
<h5 id="_n4js-di-withparentinjector"><a class="anchor" href="#_n4js-di-withparentinjector"></a><a class="link" href="#_n4js-di-withparentinjector">11.2.6.2. N4JS DI @WithParentInjector</a></h5>
<table class="tableblock frame-none grid-none spread">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">name</dt>
<dd>
<p>@WithParentInjector</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">targets</dt>
<dd>
<p>N4Class</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">retention policy</dt>
<dd>
<p>RUNTIME</p>
</dd>
</dl>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">transitive</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">repeatable</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">arguments</dt>
<dd>
<p>TypeRef</p>
</dd>
</dl>
</div></div></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p><code>@WithParentInjector</code> marks given <em>injector</em> as depended on other <em>injector</em>.
The depended <em>injector</em> may use provided <em>injector</em> to create instances of objects required in its object graph.</p>
</div>
<div class="paragraph">
<p>Additional <em>WithParentInjector</em> constraints:</p>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-145"></a><strong>Req. IDE-145:</strong> <a href="#Req-IDE-145">DI WithParentInjector</a> (ver. 1)</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Allowed only on <code>N4ClassDeclarations</code> annotated with <code>@GenerateInjector</code>.</p>
</li>
<li>
<p>Its parameter can only be <code>N4ClassDeclarations</code> annotated with .</p>
</li>
</ol>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="_n4js-di-usebinder"><a class="anchor" href="#_n4js-di-usebinder"></a><a class="link" href="#_n4js-di-usebinder">11.2.6.3. N4JS DI @UseBinder</a></h5>
<table class="tableblock frame-none grid-none spread">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">name</dt>
<dd>
<p>@UseBinder</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">targets</dt>
<dd>
<p>N4Class</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">retention policy</dt>
<dd>
<p>RUNTIME</p>
</dd>
</dl>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">transitive</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">arguments</dt>
<dd>
<p>TypeRef</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">arguments are optional</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p><code>@UseBinder</code> describes <em>Binder</em> to be used (configure) target <em>Injector</em>.</p>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-146"></a><strong>Req. IDE-146:</strong> <a href="#Req-IDE-146">DI UseInjector</a> (ver. 1)</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Allowed only on <code>N4ClassDeclarations</code> annotated with <code>@GenerateInjector</code>.</p>
</li>
<li>
<p>Its parameter can only be <code>N4ClassDeclarations</code> annotated with <code>@Binder</code>.</p>
</li>
</ol>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="_n4js-di-binder"><a class="anchor" href="#_n4js-di-binder"></a><a class="link" href="#_n4js-di-binder">11.2.6.4. N4JS DI @Binder</a></h5>
<table class="tableblock frame-none grid-none spread">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">name</dt>
<dd>
<p>@Binder</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">targets</dt>
<dd>
<p>N4Class</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">retention policy</dt>
<dd>
<p>RUNTIME</p>
</dd>
</dl>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">transitive</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">repeatable</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">arguments</dt>
<dd>
<p>NONE</p>
</dd>
</dl>
</div></div></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p><code>@Binder</code> defines a list of bind configurations.
That can be either <code>@Bind</code> annotations on <code>@Binder</code> itself or its factory methods annotated with <code>@Provides</code>.</p>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-147"></a><strong>Req. IDE-147:</strong> <a href="#Req-IDE-147">DI binder</a> (ver. 1)</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Target <code>N4ClassDeclaration</code> must not be <em>abstract</em>.</p>
</li>
<li>
<p>Target <code>N4ClassDeclaration</code>  must not be annotated with <code>@GenerateInjector</code>.</p>
</li>
<li>
<p>Target class cannot have <em>injection points</em>.</p>
</li>
</ol>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="_n4js-di-bind"><a class="anchor" href="#_n4js-di-bind"></a><a class="link" href="#_n4js-di-bind">11.2.6.5. N4JS DI @Bind</a></h5>
<table class="tableblock frame-none grid-none spread">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">name</dt>
<dd>
<p>@Bind</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">targets</dt>
<dd>
<p>N4ClassDeclaration</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">retention policy</dt>
<dd>
<p>RUNTIME</p>
</dd>
</dl>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">transitive</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">arguments</dt>
<dd>
<p>TypeRef key, TypeRef target</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">arguments are optional</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>Defines <em>binding</em> between type and subtype that will be used by injector when configured with target <a href="#_n4js-di-binder">N4JS DI @Binder</a>.
See also <a href="#_validation-of-callsites-targeting-n4injector-methods">Validation of callsites targeting N4Injector methods</a> for description of injectable types.</p>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-148"></a><strong>Req. IDE-148:</strong> <a href="#Req-IDE-148">DI Bind</a> (ver. 1)</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Allowed only on <code>N4ClassDeclarations</code> that are annotated with <code>@Binder</code>(<a href="#_n4js-di-binder">N4JS DI @Binder</a>).</p>
</li>
<li>
<p>Parameters are instances of one of the values described in <a href="#_validation-of-callsites-targeting-n4injector-methods">Validation of callsites targeting N4Injector methods</a>.</p>
</li>
<li>
<p>The second parameter must be a subtype of the first one.</p>
</li>
</ol>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="_n4js-di-provides"><a class="anchor" href="#_n4js-di-provides"></a><a class="link" href="#_n4js-di-provides">11.2.6.6. N4JS DI @Provides</a></h5>
<table class="tableblock frame-none grid-none spread">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">name</dt>
<dd>
<p>@Provides</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">targets</dt>
<dd>
<p>N4MethodDeclaration</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">retention policy</dt>
<dd>
<p>RUNTIME</p>
</dd>
</dl>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">transitive</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">repeatable</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">arguments</dt>
<dd>
<p>NONE</p>
</dd>
</dl>
</div></div></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p><code>@Provides</code> marks <em>factory method</em> to be used as part <a href="appendix_a_acronyms.html#AC">DI</a>.
This is treated as <em>explicit binding</em> between declared return type and actual return type.
This method is expected to be part of the <code>@Binder</code>.
Can be used to implement custom scopes.</p>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-149"></a><strong>Req. IDE-149:</strong> <a href="#Req-IDE-149">DI Provides</a> (ver. 1)</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Allowed only on <code>N4MethodDeclarations</code> that are part of a classifier annotated with <code>@Binder</code>.</p>
</li>
<li>
<p>Annotated method declared type returns instance of one of the types described in <em>injectable values</em>  <a href="#_validation-of-callsites-targeting-n4injector-methods">Validation of callsites targeting N4Injector methods</a>.</p>
</li>
</ol>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="_n4js-di-inject"><a class="anchor" href="#_n4js-di-inject"></a><a class="link" href="#_n4js-di-inject">11.2.6.7. N4JS DI @Inject</a></h5>
<table class="tableblock frame-none grid-none spread">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">name</dt>
<dd>
<p>@Inject</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">targets</dt>
<dd>
<p>N4Field, N4Method, constructor</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">retention policy</dt>
<dd>
<p>RUNTIME</p>
</dd>
</dl>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">transitive</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">repeatable</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">arguments</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p><code>@Inject</code> defines the injection point into which an instance object will be injected.
The specific instance depends on the injector configuration (bindings) used.
Class fields, methods and constructors can be annotated. See <a href="#_injection-points">Injection Points</a> for more information.</p>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-150"></a><strong>Req. IDE-150:</strong> <a href="#Req-IDE-150">DI Inject</a> (ver. 1)</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Injection point bindings need to be resolvable.</p>
</li>
<li>
<p>Binding for given type must not be duplicated.</p>
</li>
<li>
<p>Annotated types must be instances of one of the types described in <a href="#_validation-of-callsites-targeting-n4injector-methods">Validation of callsites targeting N4Injector methods</a>.</p>
</li>
</ol>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="_n4js-di-singleton"><a class="anchor" href="#_n4js-di-singleton"></a><a class="link" href="#_n4js-di-singleton">11.2.6.8. N4JS DI @Singleton</a></h5>
<table class="tableblock frame-none grid-none spread">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">name</dt>
<dd>
<p>@Singleton</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">targets</dt>
<dd>
<p>N4Class</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">retention policy</dt>
<dd>
<p>RUNTIME</p>
</dd>
</dl>
</div></div></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">transitive</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">repeatable</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
<td class="tableblock halign-left valign-top"><div><div class="dlist">
<dl>
<dt class="hdlist1">arguments</dt>
<dd>
<p>NO</p>
</dd>
</dl>
</div></div></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>In the case of annotating a class <code>S</code> with <code>@Singleton</code> on the definition-site, the singleton scope will be used as described in <a href="#_singleton-scope">Singleton Scope</a>.</p>
</div>
</div>
</div>
</div>
<div class="sect2 language-n4js">
<h3 id="_test-support"><a class="anchor" href="#_test-support"></a><a class="link" href="#_test-support">11.3. Test Support</a></h3>
<div class="paragraph">
<p>N4JS provides some annotations for testing. Most of these annotations are similar to annotations found in JUnit 4.
For details see our Mangelhaft test framework (stdlib specification) and the N4JS-IDE specification.</p>
</div>
<div class="paragraph">
<p>In order to enable tests for private methods, test projects may define which project they are testing.</p>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-151"></a><strong>Req. IDE-151:</strong> <a href="#Req-IDE-151">Test API methods and types</a> (ver. 1)</p>
</div>
<div class="paragraph">
<p>In some cases, types or methods are only provided for testing purposes.
In order to improve usability, e.g. content assist, these types and methods can be annotated with <code>@TestAPI</code>.
There are no constraints defined for that annotation at the moment.</p>
</div>
</div>
</div>
</div>
<div class="sect2 language-n4js">
<h3 id="_polyfill-definitions"><a class="anchor" href="#_polyfill-definitions"></a><a class="link" href="#_polyfill-definitions">11.4. Polyfill Definitions</a></h3>
<div class="paragraph">
<p>In plain JavaScript, so called <em>polyfill</em> (or sometimes called <em>shim</em>) libraries are provided in order to modify existing classes which are only prototypes in plain JavaScript.
In N4JS, this can be defined for declarations via the annotation <code>@Polyfill</code> or <code>@StaticPolyfill</code>.
One of these annotations can be added to class declarations which do not look that much different from normal classes.
In the case of polyfill classes, the extended class is modified (or filled) instead of being subclassed. It is therefore valid to polyfill a class even if it is declared <code>@Final</code>.</p>
</div>
<div class="paragraph">
<p>We distinguish two flavours of polyfill classes: runtime and static.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Runtime polyfilling covers type enrichment for runtime libraries.
For type modifications the annotation <code>@Polyfill</code> is used.</p>
</li>
<li>
<p>Static polyfilling covers code modifications for adapting generated code.
The annotation <code>@StaticPolyfill</code> denotes a polyfill in ordinary code, which usually provides executable implementations.</p>
</li>
</ul>
</div>
<div class="openblock definition">
<div class="content">
<div class="paragraph">
<p><a id="polyfill_class"></a><strong>Definition:</strong> <a href="#polyfill_class">Polyfill Class</a></p>
</div>
<div class="paragraph">
<p>A <em>polyfill class</em> (or simply <em>polyfill</em>) is
a class modifying an existing one. The polyfill is not a new class (or type) on its own.
Instead, new members defined in the polyfill are added to the modified class and existing members can be modified similarly to overriding.
We call the modified class the <em>filled</em> class and the modification <em>filling</em>.</p>
</div>
<div class="paragraph">
<p>We add a new pseudo property <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>p</mi><mi>o</mi><mi>l</mi><mi>y</mi><mi>f</mi><mi>i</mi><mi>l</mi><mi>l</mi></math> to classes in order to distinguish between normal (sub-) classes and polyfill classes.</p>
</div>
</div>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-152"></a><strong>Req. IDE-152:</strong> <a href="#Req-IDE-152">Polyfill Class</a> (ver. 1)</p>
</div>
<div class="paragraph">
<p>For a polyfill class <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>P</mi></math> annotated with <code>@Polyfill</code> or  <code>@StaticPolyfill</code>, that is <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>P</mi><mo>.</mo><mi>p</mi><mi>o</mi><mi>l</mi><mi>y</mi><mi>f</mi><mi>i</mi><mi>l</mi><mi>l</mi><mo>=</mo><mstyle mathvariant="monospace"><mtext>true</mtext></mstyle></math>, all the following constraints must hold:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>P</mi></math> must extend a class <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>F</mi></math>, <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>F</mi></math> is called the filled class:</p>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mi>P</mi><mo>.</mo><mi>s</mi><mi>u</mi><mi>p</mi><mi>e</mi><mi>r</mi><mo>=</mo><mi>F</mi></math>
</div>
</div>
</li>
<li>
<p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>P</mi></math>’s name equals the name of the filled class and is contained in a module with same qualified name (specifier or global):<br></p>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mtable><mtr><mtd><mspace width="3.0mm"/><mi>P</mi><mo>.</mo><mi>n</mi><mi>a</mi><mi>m</mi><mi>e</mi><mo>=</mo><mi>F</mi><mo>.</mo><mi>n</mi><mi>a</mi><mi>m</mi><mi>e</mi></mtd></mtr><mtr><mtd><mspace width="3.0mm"/><mo>∧</mo><mi>P</mi><mo>.</mo><mi>c</mi><mi>o</mi><mi>n</mi><mi>t</mi><mi>a</mi><mi>i</mi><mi>n</mi><mi>e</mi><mi>d</mi><mi>M</mi><mi>o</mi><mi>d</mi><mi>u</mi><mi>l</mi><mi>e</mi><mo>.</mo><mi>g</mi><mi>l</mi><mi>o</mi><mi>b</mi><mi>a</mi><mi>l</mi><mo>=</mo><mi>F</mi><mo>.</mo><mi>c</mi><mi>o</mi><mi>n</mi><mi>t</mi><mi>a</mi><mi>i</mi><mi>n</mi><mi>e</mi><mi>d</mi><mi>M</mi><mi>o</mi><mi>d</mi><mi>u</mi><mi>l</mi><mi>e</mi><mo>.</mo><mi>g</mi><mi>l</mi><mi>o</mi><mi>b</mi><mi>a</mi><mi>l</mi></mtd></mtr><mtr><mtd><mspace width="3.0mm"/><mo>∧</mo><mrow><mo>(</mo><mi>P</mi><mo>.</mo><mi>c</mi><mi>o</mi><mi>n</mi><mi>t</mi><mi>a</mi><mi>i</mi><mi>n</mi><mi>e</mi><mi>d</mi><mi>M</mi><mi>o</mi><mi>d</mi><mi>u</mi><mi>l</mi><mi>e</mi><mo>.</mo><mi>g</mi><mi>l</mi><mi>o</mi><mi>b</mi><mi>a</mi><mi>l</mi></mrow></mtd></mtr><mtr><mtd><mrow><mspace width="3.0mm"/><mspace width="3.0em"/><mo>∨</mo><mi>P</mi><mo>.</mo><mi>c</mi><mi>o</mi><mi>n</mi><mi>t</mi><mi>a</mi><mi>i</mi><mi>n</mi><mi>e</mi><mi>d</mi><mi>M</mi><mi>o</mi><mi>d</mi><mi>u</mi><mi>l</mi><mi>e</mi><mo>.</mo><mi>s</mi><mi>p</mi><mi>e</mi><mi>c</mi><mi>i</mi><mi>f</mi><mi>i</mi><mi>e</mi><mi>r</mi><mo>=</mo><mi>F</mi><mo>.</mo><mi>c</mi><mi>o</mi><mi>n</mi><mi>t</mi><mi>a</mi><mi>i</mi><mi>n</mi><mi>e</mi><mi>d</mi><mi>M</mi><mi>o</mi><mi>d</mi><mi>u</mi><mi>l</mi><mi>e</mi><mo>.</mo><mi>s</mi><mi>p</mi><mi>e</mi><mi>c</mi><mi>i</mi><mi>f</mi><mi>i</mi><mi>e</mi><mi>r</mi><mo>)</mo></mrow></mtd></mtr></mtable></math>
</div>
</div>
</li>
<li>
<p>Both the polyfill and filled class must be top-level declarations (i.e., no class expression):<br></p>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mi>P</mi><mo>.</mo><mi>t</mi><mi>o</mi><mi>p</mi><mi>L</mi><mi>e</mi><mi>v</mi><mi>e</mi><mi>l</mi><mo>=</mo><mstyle mathvariant="monospace"><mtext>true</mtext></mstyle><mo>∧</mo><mi>F</mi><mo>.</mo><mi>t</mi><mi>o</mi><mi>p</mi><mi>L</mi><mi>e</mi><mi>v</mi><mi>e</mi><mi>l</mi><mo>=</mo><mstyle mathvariant="monospace"><mtext>true</mtext></mstyle></math>
</div>
</div>
</li>
<li>
<p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>P</mi></math> must not implement any interfaces:</p>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mi>P</mi><mo>.</mo><mi>i</mi><mi>m</mi><mi>p</mi><mi>l</mi><mi>e</mi><mi>m</mi><mi>e</mi><mi>n</mi><mi>t</mi><mi>e</mi><mi>d</mi><mi>I</mi><mi>n</mi><mi>t</mi><mi>e</mi><mi>r</mi><mi>f</mi><mi>a</mi><mi>c</mi><mi>e</mi><mi>s</mi><mo>=</mo><mi>∅</mi></math>
</div>
</div>
</li>
<li>
<p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>P</mi></math> must have the same access modifier (access, abstract, final) as the filled class:<br></p>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mtable><mtr><mtd><mi>P</mi><mo>.</mo><mi>a</mi><mi>c</mi><mi>c</mi><mi>e</mi><mi>s</mi><mi>s</mi><mi>M</mi><mi>o</mi><mi>d</mi><mi>i</mi><mi>f</mi><mi>i</mi><mi>e</mi><mi>r</mi><mo>=</mo><mi>F</mi><mo>.</mo><mi>a</mi><mi>c</mi><mi>c</mi><mi>e</mi><mi>s</mi><mi>s</mi><mi>M</mi><mi>o</mi><mi>d</mi><mi>i</mi><mi>f</mi><mi>i</mi><mi>e</mi><mi>r</mi></mtd></mtr><mtr><mtd><mi>P</mi><mo>.</mo><mi>a</mi><mi>b</mi><mi>s</mi><mi>t</mi><mi>r</mi><mi>a</mi><mi>c</mi><mi>t</mi><mo>=</mo><mi>F</mi><mo>.</mo><mi>a</mi><mi>b</mi><mi>s</mi><mi>t</mi><mi>r</mi><mi>a</mi><mi>c</mi><mi>t</mi></mtd></mtr><mtr><mtd><mi>P</mi><mo>.</mo><mi>f</mi><mi>i</mi><mi>n</mi><mi>a</mi><mi>l</mi><mo>=</mo><mi>F</mi><mo>.</mo><mi>f</mi><mi>i</mi><mi>n</mi><mi>a</mi><mi>l</mi></mtd></mtr></mtable></math>
</div>
</div>
</li>
<li>
<p>If <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>P</mi></math> declares a constructor, it must be override compatible with the constructor of the filled class:</p>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mo>∃</mo><mi>P</mi><mo>.</mo><mi>o</mi><mi>w</mi><mi>n</mi><mi>e</mi><mi>d</mi><mi>C</mi><mi>t</mi><mi>o</mi><mi>r</mi><mi>:</mi><mi>P</mi><mo>.</mo><mi>o</mi><mi>w</mi><mi>n</mi><mi>e</mi><mi>d</mi><mi>C</mi><mi>t</mi><mi>o</mi><mi>r</mi><mspace width="1.0mm"/><mo>&lt;</mo><mstyle mathvariant="monospace"><mtext>:</mtext></mstyle><mspace width="1.0mm"/><mi>F</mi><mo>.</mo><mi>c</mi><mi>t</mi><mi>o</mi><mi>r</mi></math>
</div>
</div>
</li>
<li>
<p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>P</mi></math> must define the same type variables as the filled class <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>F</mi></math> and the arguments must be in the same order as the parameters (with no further modifications):</p>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mtable><mtr><mtd><mo>∀</mo><mi>i</mi><mo>,</mo><mn>0</mn><mo>≤</mo><mi>i</mi><mo>&lt;</mo><mo>|</mo><mi>P</mi><mo>.</mo><mi>t</mi><mi>y</mi><mi>p</mi><mi>e</mi><mi>P</mi><mi>a</mi><mi>r</mi><mi>s</mi><mo>|</mo><mi>:</mi></mtd></mtr><mtr><mtd><mspace width="3.0em"/><mi>P</mi><mo>.</mo><mi>t</mi><mi>y</mi><mi>p</mi><mi>e</mi><mi>P</mi><mi>a</mi><mi>r</mi><msub><mi>s</mi><mi>i</mi></msub><mo>=</mo><mi>F</mi><mo>.</mo><mi>t</mi><mi>y</mi><mi>p</mi><mi>e</mi><mi>P</mi><mi>a</mi><mi>r</mi><msub><mi>s</mi><mi>i</mi></msub></mtd></mtr><mtr><mtd><mspace width="3.0em"/><mo>∧</mo><mi>P</mi><mo>.</mo><mi>t</mi><mi>y</mi><mi>p</mi><mi>e</mi><mi>P</mi><mi>a</mi><mi>r</mi><msub><mi>s</mi><mi>i</mi></msub><mo>.</mo><mi>n</mi><mi>a</mi><mi>m</mi><mi>e</mi><mo>=</mo><mi>P</mi><mo>.</mo><mi>s</mi><mi>u</mi><mi>p</mi><mi>e</mi><mi>r</mi><mo>.</mo><mi>t</mi><mi>y</mi><mi>p</mi><mi>e</mi><mi>A</mi><mi>r</mi><mi>g</mi><msub><mi>s</mi><mi>i</mi></msub><mo>.</mo><mi>n</mi><mi>a</mi><mi>m</mi><mi>e</mi></mtd></mtr></mtable></math>
</div>
</div>
</li>
<li>
<p>All constraints related to member redefinition (cf. <a href="classifiers.html#_redefinition-of-members">Redefinition of Members</a>) have to hold.
In the case of polyfills, this is true for constructors (cf. <a href="classifiers.html#Req-IDE-72">[Req-IDE-72]</a>) and private members.</p>
</li>
</ol>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_runtime-polyfill-definitions"><a class="anchor" href="#_runtime-polyfill-definitions"></a><a class="link" href="#_runtime-polyfill-definitions">11.4.1. Runtime Polyfill Definitions</a></h4>
<div class="paragraph">
<p>(Runtime) Libraries often do not provide completely new types but modify existing types.
The ECMA-402 Internationalization Standard [<a href="appendix_c_bibliography.html#ECMA12a">ECMA12a</a>], for example, changes methods of the built-in class <code>Date</code> to be timezone aware.
Other scenarios include new functionality provided by browsers which are not part of an official standard yet.
Even ECMAScript 6 [<a href="appendix_c_bibliography.html#ECMA15a">ECMA15a</a>] extends the predecessor [<a href="appendix_c_bibliography.html#ECMA11a">ECMA11a</a>]  in terms of new methods (or new method parameters) added to existing types (it also adds completely new classes and features, of course).</p>
</div>
<div class="paragraph">
<p>Runtime polyfills are only applicable to runtime libraries or environments and thus are limited to n4jsd files.</p>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-153"></a><strong>Req. IDE-153:</strong> <a href="#Req-IDE-153">Runtime Polyfill Class</a> (ver. 1)</p>
</div>
<div class="paragraph">
<p>For a runtime-polyfill class <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>P</mi></math> annotated with <code>@Polyfill</code>, that is <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>P</mi><mo>.</mo><mi>s</mi><mi>t</mi><mi>a</mi><mi>t</mi><mi>i</mi><mi>c</mi><mi>p</mi><mi>o</mi><mi>l</mi><mi>y</mi><mi>f</mi><mi>i</mi><mi>l</mi><mi>l</mi><mo>=</mo><mstyle mathvariant="monospace"><mtext>false</mtext></mstyle></math>, all the following constraints must hold in addition to <a href="#Req-IDE-152">[Req-IDE-152]</a>:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Both the polyfill and filled class are provided by the runtime
(annotated with <code>@ProvidedByRuntime</code>): <sup class="footnote">[<a id="_footnoteref_59" class="footnote" href="appendix_c_bibliography.html#_footnote_59" title="View footnote.">59</a>]</sup></p>
</li>
</ol>
</div>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mi>P</mi><mo>.</mo><mi>p</mi><mi>r</mi><mi>o</mi><mi>v</mi><mi>i</mi><mi>d</mi><mi>e</mi><mi>d</mi><mi>B</mi><mi>y</mi><mi>R</mi><mi>u</mi><mi>n</mi><mi>t</mi><mi>i</mi><mi>m</mi><mi>e</mi><mo>=</mo><mstyle mathvariant="monospace"><mtext>true</mtext></mstyle><mo>∧</mo><mi>F</mi><mo>.</mo><mi>p</mi><mi>r</mi><mi>o</mi><mi>v</mi><mi>i</mi><mi>d</mi><mi>e</mi><mi>d</mi><mi>B</mi><mi>y</mi><mi>R</mi><mi>u</mi><mi>n</mi><mi>t</mi><mi>i</mi><mi>m</mi><mi>e</mi><mo>=</mo><mstyle mathvariant="monospace"><mtext>true</mtext></mstyle></math>
</div>
</div>
</div>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-154"></a><strong>Req. IDE-154:</strong> <a href="#Req-IDE-154">Applying Polyfills</a> (ver. 1)</p>
</div>
<div class="paragraph">
<p>A polyfill is automatically applied if a runtime library or environment required by the current project provides it. In this case, the following constraints must hold:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>No member must be filled by more than one polyfill.</p>
</li>
</ol>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_static-polyfill-definitions"><a class="anchor" href="#_static-polyfill-definitions"></a><a class="link" href="#_static-polyfill-definitions">11.4.2. Static Polyfill Definitions</a></h4>
<div class="paragraph">
<p>Static polyfilling is a compile time feature to enrich the definition and usually also the implementation of generated code in N4JS. It is related to runtime polyfilling described in <a href="#_runtime-polyfill-definitions">Runtime Polyfill Definitions</a> in a sense that both fillings enrich the types they address. Despite this, static polyfilling and runtime polyfilling differ in the way they are handled.</p>
</div>
<div class="paragraph">
<p>Static polyfills usually provide executable implementations and are thus usually found in n4js files. However, they are allowed in n4jsd files, as well, for example to enrich generated code in an API project.</p>
</div>
<div class="paragraph">
<p>The motivation for static polyfills is to support automatic code generation.
In many cases, automatically generated code is missing some information to make it sufficiently usable in the desired environment.
Manual enhancements usually need to be applied.
If we think of a toolchain, the question may arise how to preserve the manual work when a
regeneration is triggered. Static polyfilling allows the separation of generated code and manual adjustments in separate files.
The transpiler merges the two files into a single transpiled file.
To enable this behaviour, the statically fillable types must be contained in a module annotated with <code>@StaticPolyfillAware</code>.
The filling types must also be annotated with <code>@StaticPolyfill</code> and be contained in a different module with same specifier but annotated with <code>@StaticPolyfillModule</code>.
Static polyfilling is restricted to a project, thus the module to be filled as well as the filling module must be contained in the same project.</p>
</div>
<div class="paragraph">
<p>We add a new pseudo property <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>s</mi><mi>t</mi><mi>a</mi><mi>t</mi><mi>i</mi><mi>c</mi><mi>P</mi><mi>o</mi><mi>l</mi><mi>y</mi><mi>f</mi><mi>i</mi><mi>l</mi><mi>l</mi></math> to classes in order to distinguish between normal (sub-) classes and static polyfill classes.
We add two new pseudo properties to modules in order to modify the transpilation process.
The mutually-exclusive properties <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>s</mi><mi>t</mi><mi>a</mi><mi>t</mi><mi>i</mi><mi>c</mi><mi>P</mi><mi>o</mi><mi>l</mi><mi>y</mi><mi>f</mi><mi>i</mi><mi>l</mi><mi>l</mi><mi>A</mi><mi>w</mi><mi>a</mi><mi>r</mi><mi>e</mi></math> and <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>s</mi><mi>t</mi><mi>a</mi><mi>t</mi><mi>i</mi><mi>c</mi><mi>P</mi><mi>o</mi><mi>l</mi><mi>y</mi><mi>f</mi><mi>i</mi><mi>l</mi><mi>l</mi></math> signal the way these files are processed.</p>
</div>
<div class="paragraph">
<p>In order to support efficient transpilation, the following constraint must hold in addition to constraints:</p>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-155"></a><strong>Req. IDE-155:</strong> <a href="#Req-IDE-155">Static Polyfill Layout</a> (ver. 1)</p>
</div>
<div class="paragraph">
<p>For a static polyfill class <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>P</mi></math> annotated with <code>@StaticPolyfill</code>, that is <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>P</mi><mo>.</mo><mi>s</mi><mi>t</mi><mi>a</mi><mi>t</mi><mi>i</mi><mi>c</mi><mi>p</mi><mi>o</mi><mi>l</mi><mi>y</mi><mi>f</mi><mi>i</mi><mi>l</mi><mi>l</mi><mo>=</mo><mstyle mathvariant="monospace"><mtext>true</mtext></mstyle></math>, all the following constraints must hold in addition to <a href="#Req-IDE-152">[Req-IDE-152]</a>:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p><math xmlns="http://www.w3.org/1998/Math/MathML"><mi>P</mi></math>’s name equals the name of the filled class and is contained in a module with the same qualified name:</p>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mtable><mtr><mtd><mi>P</mi><mo>.</mo><mi>n</mi><mi>a</mi><mi>m</mi><mi>e</mi><mo>=</mo><mi>F</mi><mo>.</mo><mi>n</mi><mi>a</mi><mi>m</mi><mi>e</mi></mtd></mtr><mtr><mtd><mo>∧</mo><mi>P</mi><mo>.</mo><mi>c</mi><mi>o</mi><mi>n</mi><mi>t</mi><mi>a</mi><mi>i</mi><mi>n</mi><mi>e</mi><mi>d</mi><mi>M</mi><mi>o</mi><mi>d</mi><mi>u</mi><mi>l</mi><mi>e</mi><mo>.</mo><mi>s</mi><mi>p</mi><mi>e</mi><mi>c</mi><mi>i</mi><mi>f</mi><mi>i</mi><mi>e</mi><mi>r</mi><mo>=</mo><mi>F</mi><mo>.</mo><mi>c</mi><mi>o</mi><mi>n</mi><mi>t</mi><mi>a</mi><mi>i</mi><mi>n</mi><mi>e</mi><mi>d</mi><mi>M</mi><mi>o</mi><mi>d</mi><mi>u</mi><mi>l</mi><mi>e</mi><mo>.</mo><mi>s</mi><mi>p</mi><mi>e</mi><mi>c</mi><mi>i</mi><mi>f</mi><mi>i</mi><mi>e</mi><mi>r</mi></mtd></mtr></mtable></math>
</div>
</div>
</li>
<li>
<p>Both the static polyfill and the filled class are part of the same project:</p>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mi>P</mi><mo>.</mo><mi>p</mi><mi>r</mi><mi>o</mi><mi>j</mi><mi>e</mi><mi>c</mi><mi>t</mi><mo>=</mo><mi>F</mi><mo>.</mo><mi>p</mi><mi>r</mi><mi>o</mi><mi>j</mi><mi>e</mi><mi>c</mi><mi>t</mi></math>
</div>
</div>
</li>
<li>
<p>The filled class must be contained in a module annotated with <code>@StaticPolyfillAware</code>:</p>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mi>F</mi><mo>.</mo><mi>c</mi><mi>o</mi><mi>n</mi><mi>t</mi><mi>a</mi><mi>i</mi><mi>n</mi><mi>e</mi><mi>d</mi><mi>M</mi><mi>o</mi><mi>d</mi><mi>u</mi><mi>l</mi><mi>e</mi><mo>.</mo><mi>s</mi><mi>t</mi><mi>a</mi><mi>t</mi><mi>i</mi><mi>c</mi><mi>P</mi><mi>o</mi><mi>l</mi><mi>y</mi><mi>f</mi><mi>i</mi><mi>l</mi><mi>l</mi><mi>A</mi><mi>w</mi><mi>a</mi><mi>r</mi><mi>e</mi><mo>=</mo><mstyle mathvariant="monospace"><mtext>true</mtext></mstyle></math>
</div>
</div>
</li>
<li>
<p>The static polyfill and the filled type must both be declared in an n4js file or both in an n4jsd file.</p>
</li>
<li>
<p>The filling class must be contained in a module annotated with <code>@StaticPolyfillModule</code>:</p>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mi>P</mi><mo>.</mo><mi>c</mi><mi>o</mi><mi>n</mi><mi>t</mi><mi>a</mi><mi>i</mi><mi>n</mi><mi>e</mi><mi>d</mi><mi>M</mi><mi>o</mi><mi>d</mi><mi>u</mi><mi>l</mi><mi>e</mi><mo>.</mo><mi>s</mi><mi>t</mi><mi>a</mi><mi>t</mi><mi>i</mi><mi>c</mi><mi>P</mi><mi>o</mi><mi>l</mi><mi>y</mi><mi>f</mi><mi>i</mi><mi>l</mi><mi>l</mi><mi>M</mi><mi>o</mi><mi>d</mi><mi>u</mi><mi>l</mi><mi>e</mi><mo>=</mo><mstyle mathvariant="monospace"><mtext>true</mtext></mstyle></math>
</div>
</div>
</li>
<li>
<p>For a statically-filled class <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>F</mi></math> there is at most one static polyfill:</p>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mfenced close=")" open="("><mrow><msub><mi>P</mi><mn>1</mn></msub><mstyle mathvariant="monospace"><mspace width="1ex"/><mtext>is static polyfill of</mtext><mspace width="1ex"/></mstyle><mi>F</mi><mo>∧</mo><msub><mi>P</mi><mn>2</mn></msub><mstyle mathvariant="monospace"><mspace width="1ex"/><mtext>is static polyfill of</mtext><mspace width="1ex"/></mstyle><mi>F</mi></mrow></mfenced><mo>→</mo><msub><mi>P</mi><mn>1</mn></msub><mo>=</mo><msub><mi>P</mi><mn>2</mn></msub></math>
</div>
</div>
</li>
</ol>
</div>
</div>
</div>
<div class="openblock requirement">
<div class="content">
<div class="paragraph">
<p><a id="Req-IDE-156"></a><strong>Req. IDE-156:</strong> <a href="#Req-IDE-156">Restrictions on static polyfilling</a> (ver. 1)</p>
</div>
<div class="paragraph">
<p>For a static polyfilling module <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>M</mi><mi>P</mi></msub></math> the following must hold:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>All top-level elements are static polyfills:</p>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mfrac><mrow><mo>∀</mo><mi>T</mi><mo>∈</mo><msub><mi>M</mi><mi>P</mi></msub><mo>∧</mo><mi>T</mi><mo>.</mo><mi>t</mi><mi>o</mi><mi>p</mi><mi>L</mi><mi>e</mi><mi>v</mi><mi>e</mi><mi>l</mi><mo>=</mo><mstyle mathvariant="monospace"><mtext>true</mtext></mstyle></mrow><mrow><mi>T</mi><mo>.</mo><mi>s</mi><mi>t</mi><mi>a</mi><mi>t</mi><mi>i</mi><mi>c</mi><mi>P</mi><mi>o</mi><mi>l</mi><mi>y</mi><mi>f</mi><mi>i</mi><mi>l</mi><mi>l</mi><mo>=</mo><mstyle mathvariant="monospace"><mtext>true</mtext></mstyle></mrow></mfrac></math>
</div>
</div>
</li>
<li>
<p>It exists exactly one filled module <math xmlns="http://www.w3.org/1998/Math/MathML"><msub><mi>M</mi><mi>F</mi></msub></math> annotated with <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>s</mi><mi>t</mi><mi>a</mi><mi>t</mi><mi>i</mi><mi>c</mi><mi>P</mi><mi>o</mi><mi>l</mi><mi>y</mi><mi>f</mi><mi>i</mi><mi>l</mi><mi>l</mi><mi>A</mi><mi>w</mi><mi>a</mi><mi>r</mi><mi>e</mi></math> in the same project.</p>
</li>
<li>
<p>It is an error if two static polyfill modules for the same filled module exist in the same project:</p>
<div class="openblock">
<div class="content">
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><mfrac><mrow><msub><mi>M</mi><mn>1.</mn></msub><mi>s</mi><mi>p</mi><mi>e</mi><mi>c</mi><mi>i</mi><mi>f</mi><mi>i</mi><mi>e</mi><mi>r</mi><mo>=</mo><msub><mi>M</mi><mn>2.</mn></msub><mi>s</mi><mi>p</mi><mi>e</mi><mi>c</mi><mi>i</mi><mi>f</mi><mi>i</mi><mi>e</mi><mi>r</mi><mo>∧</mo><msub><mi>M</mi><mn>1.</mn></msub><mi>p</mi><mi>r</mi><mi>o</mi><mi>j</mi><mi>e</mi><mi>c</mi><mi>t</mi><mo>=</mo><msub><mi>M</mi><mn>2.</mn></msub><mi>p</mi><mi>r</mi><mi>o</mi><mi>j</mi><mi>e</mi><mi>c</mi><mi>t</mi><mtext>
</mtext><mo>∧</mo><msub><mi>M</mi><mn>1.</mn></msub><mi>s</mi><mi>t</mi><mi>a</mi><mi>t</mi><mi>i</mi><mi>c</mi><mi>P</mi><mi>o</mi><mi>l</mi><mi>y</mi><mi>f</mi><mi>i</mi><mi>l</mi><mi>l</mi><mi>M</mi><mi>o</mi><mi>d</mi><mi>u</mi><mi>l</mi><mo>=</mo><msub><mi>M</mi><mn>2.</mn></msub><mi>s</mi><mi>t</mi><mi>a</mi><mi>t</mi><mi>i</mi><mi>c</mi><mi>P</mi><mi>o</mi><mi>l</mi><mi>y</mi><mi>f</mi><mi>i</mi><mi>l</mi><mi>l</mi><mi>M</mi><mi>o</mi><mi>d</mi><mi>u</mi><mi>l</mi><mo>=</mo><mstyle mathvariant="monospace"><mtext>true</mtext></mstyle></mrow><mrow><msub><mi>M</mi><mn>1</mn></msub><mo>=</mo><msub><mi>M</mi><mn>2</mn></msub></mrow></mfrac></math>
</div>
</div>
</li>
</ol>
</div>
</div>
</div>
<div class="exampleblock">
<div class="title">Example 102. Static polyfill</div>
<div class="content">
<div class="paragraph">
<p><a href="#ex:staticpolyfill-genmod">Static Polyfill, Genmod</a> shows an example of generated code.
<a href="#ex:staticpolyfill-polyfillmod">Static Polyfill, Polyfillmod</a> demonstrates the static polyfill.</p>
</div>
<div class="paragraph">
<p>Note that the containing project has two source folders configured:<br>
<code>Project/src/n4js</code> and <code>Project/src/n4jsgen</code>.</p>
</div>
<div id="ex:staticpolyfill-polyfillmod" class="listingblock">
<div class="title">Static Polyfill, Polyfillmod</div>
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">@@StaticPolyfillAware
export public class A {
    constructor() {...}
    m1(): void{...}
}
export public class B {
    constructor() {...}
    m2(): void{...}
}</code></pre>
</div>
</div>
<div id="ex:staticpolyfill-genmod" class="listingblock">
<div class="title">Static Polyfill, Genmod</div>
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">@@StaticPolyfillModule
@StaticPolyfill
export public class B extends B {
    @Override
    constructor(){ ... } // replaces generated ctor of B
    @Override
    m1(): void {...} // adds overridden method m1 to B
    @Override
    m2(): void {...} // replaces method m2 in B
    m3(): void {...} // adds new method m3 to B
}</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_transpiling-static-polyfilled-classes"><a class="anchor" href="#_transpiling-static-polyfilled-classes"></a><a class="link" href="#_transpiling-static-polyfilled-classes">11.4.3. Transpiling static polyfilled classes</a></h4>
<div class="paragraph">
<p>Transpiling static polyfilled classes encounters the special case that two different <code>n4js</code> source files with the same qualified name are part of the project.
Since the current transpiler is file-based, both files would be transpiled to the same output destination and would therefore overwrite each other.
The following pre-transpilation steps handle this situation:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Current file to transpile is <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>M</mi></math></p>
</li>
<li>
<p>If <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>M</mi><mo>.</mo><mi>s</mi><mi>t</mi><mi>a</mi><mi>t</mi><mi>i</mi><mi>c</mi><mi>P</mi><mi>o</mi><mi>l</mi><mi>y</mi><mi>f</mi><mi>i</mi><mi>l</mi><mi>l</mi><mi>A</mi><mi>w</mi><mi>a</mi><mi>r</mi><mi>e</mi><mo>=</mo><mstyle mathvariant="monospace"><mtext>true</mtext></mstyle></math>, then</p>
<div class="ulist">
<ul>
<li>
<p>search for a second file <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>G</mi></math> with same qualified name:<br>
<math xmlns="http://www.w3.org/1998/Math/MathML"><mi>G</mi><mo>.</mo><mi>s</mi><mi>p</mi><mi>e</mi><mi>c</mi><mi>i</mi><mi>f</mi><mi>i</mi><mi>e</mi><mi>r</mi><mo>=</mo><mi>M</mi><mo>.</mo><mi>s</mi><mi>p</mi><mi>e</mi><mi>c</mi><mi>i</mi><mi>f</mi><mi>i</mi><mi>e</mi><mi>r</mi><mo>∧</mo><mi>G</mi><mo>.</mo><mi>p</mi><mi>r</mi><mi>o</mi><mi>j</mi><mi>e</mi><mi>c</mi><mi>t</mi><mo>=</mo><mi>M</mi><mo>.</mo><mi>p</mi><mi>r</mi><mi>o</mi><mi>j</mi><mi>e</mi><mi>c</mi><mi>t</mi></math></p>
</li>
<li>
<p>If <math xmlns="http://www.w3.org/1998/Math/MathML"><mo>∃</mo><mi>G</mi></math>, then</p>
<div class="ulist">
<ul>
<li>
<p>merge <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>G</mi></math> into current file <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>M</mi><mo>→</mo><msup><mi>M</mi><mi>'</mi></msup></math></p>
</li>
<li>
<p>conventionally transpile <math xmlns="http://www.w3.org/1998/Math/MathML"><msup><mi>M</mi><mi>'</mi></msup></math></p>
</li>
</ul>
</div>
</li>
<li>
<p>else conventionally transpile <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>M</mi></math></p>
</li>
</ul>
</div>
</li>
<li>
<p>else, if <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>M</mi><mo>.</mo><mi>s</mi><mi>t</mi><mi>a</mi><mi>t</mi><mi>i</mi><mi>c</mi><mi>P</mi><mi>o</mi><mi>l</mi><mi>y</mi><mi>f</mi><mi>i</mi><mi>l</mi><mi>l</mi><mi>M</mi><mi>o</mi><mi>d</mi><mi>u</mi><mi>l</mi><mi>e</mi><mo>=</mo><mstyle mathvariant="monospace"><mtext>true</mtext></mstyle></math>,</p>
<div class="ulist">
<ul>
<li>
<p>then <em>do nothing</em>. (Transpilation will be triggered for filled type separately.)</p>
</li>
</ul>
</div>
</li>
<li>
<p>else, conventionally transpile <math xmlns="http://www.w3.org/1998/Math/MathML"><mi>M</mi></math></p>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Version 0.9<br>
Last updated 2019-08-08 13:15:33 CEST
</div>
</div>
<!-- ************* docinfo-footer *************************************************************** -->
<div class="Grid social" style="color:#d5dfea">
  <div class="Cell Cell--2-12 m-Cell--withMargin">
    <h2>Quick Links</h2>
    <ul>
      <li><a href="../downloads.html">Download</a></li>
      <li><a href="../userguides/index.html">Documentation</a></li>
      <li><a href="https://github.com/eclipse/n4js/">Source</a></li>
      <li><a href="https://github.com/eclipse/n4js/issues">Issues</a></li>
    </ul>
  </div>
  <div class="Cell Cell--2-12 m-Cell--withMargin">
    <br/><br/>
    <ul>
      <li><a href="https://www.eclipse.org/forums/index.php/f/365/">Forum</a></li>
      <li><a href="http://n4js.blogspot.de/">Blog</a></li>
      <li><a href="https://dev.eclipse.org/mailman/listinfo/n4js-dev">Mailing List</a></li>
      <li><a href="https://projects.eclipse.org/projects/technology.n4js">Eclipse Project Page</a></li>
      <li><a href="https://twitter.com/n4jsdev">Tweets by n4jsdev</a></li>
    </ul>
  </div>
  <div class="Cell Cell--2-12 m-Cell--withMargin">
    <br/><br/>
    <ul>
      <li><a href="http://www.eclipse.org/">Eclipse Home</a></li>
      <li><a href="http://www.eclipse.org/legal/privacy.php">Privacy Policy</a></li>
      <li><a href="http://www.eclipse.org/legal/termsofuse.php">Terms of Use</a></li>
      <li><a href="http://www.eclipse.org/legal/copyright.php">Copyright Agent</a></li>
      <li><a href="http://www.eclipse.org/legal/">Legal</a></li>
    </ul>
  </div>
  <div style="clear: both; height: 0; overflow: hidden;"></div>
</div>

<!-- ************* UI Scripts ************* -->
<script type="text/javascript" src="scripts/back-to-top.js"></script>

<script type="text/javascript" src="scripts/treeview.js"></script>
<script type="text/javascript" src="scripts/toc.js"></script>

<!-- ************* Prism.js Syntax Highlighting ************* -->
<script src="scripts/prism.js"></script>

<script type="text/javascript">
	// Add the 'toclist' id for search function
	$(".toc2 > ul").attr('id', 'toclist');
	// Generate a Search input form
	$("#toclist > li:first-of-type").before('<input type="text" id="pagesearch" onkeyup="search()" placeholder="Search for section...">');
	$("#toclist > li:first-of-type").before('<i id="clear" class="fa fa-times-circle-o"></i>');
	$("#clear").click(function(){
	    $("#pagesearch").val('');
	    search();
	    $('.toc2 > ul').treeView('collapseAll');
	});
	// intialize Treeview.js
	$(".toc2 > ul").treeView();
	// Initialize Scrollspy
</script>
<!-- ************* docinfo-footer *************************************************************** -->
</body>
</html>